Server API Guide

Posit Package Manager offers a Swagger UI view, which follows the OpenAPI Specification to document the commonly requested endpoints.

Versioning of the API

The Package Manager API is considered stable, and is versioned alongside the server version. The documented endpoints are subject to change between releases. Review the release notes for a particular version for any breaking changes.

Pagination

Endpoints that return a list of results accept two query parameters, both of which begin with an underscore:

Parameter Description
_limit The maximum number of results to return.
_page The page of results to return, where one page is _limit results.

Package Manager ignores query parameters it does not recognize. It therefore answers a request that pages using a different spelling, such as offset, limit, page, or per_page, with the first page of results and reports success, rather than returning an error. When paging through a large result set, confirm that successive responses differ from one another.

_limit defaults to the [API].DefaultApiResultsLimit setting, which is 100. Package Manager reduces a larger value to the [API].MaxApiResults setting, which is 1000. For more information, refer to the API configuration settings in the appendix.

_page counts from 1, except that _page=0 also returns the first page. The second page is _page=2, the third _page=3, and so on. Package Manager rejects a negative _page or _limit with an error.

Some endpoints use their own defaults and limits in place of the configured ones. The Server API Guide documents the values that apply to each endpoint.

The bioc_version query parameter

Endpoints scoped to a repository or to a source accept a bioc_version query parameter. What it selects, and whether it is required, depends on the repository:

Repository type bioc_version
Bioconductor Selects which Bioconductor release the response is about, because the repository serves every release its Bioconductor source offers.
R Names the release the repository serves. It cannot select a different one, because the repository is subscribed to exactly one release, chosen with rspm subscribe --bioc-version.

Whether the parameter is required depends on the endpoint and on the source:

  • A mirrored Bioconductor source always requires it on a source-scoped endpoint. It is the routing hint that selects the release, so there is no default.
  • A curated Bioconductor source requires it only where the endpoint returns package content, such as a source’s package listing, which resolves a snapshot and cannot do so without a release.
  • Endpoints that only list, such as GET /repos/{repo}/transaction-dates and GET /repos/{repo}/sources/{source}/transactions, do not require it for a curated source. Omitting it on an R repository returns the subscribed release’s results, because the repository serves only that one.

A Bioconductor repository supplies the parameter for any of these endpoints, because a repository-scoped read requires it for that repository type.

On an R repository, both endpoints answer a request for a release the repository does not serve with an empty list, rather than with the subscribed release’s results. POST /url refuses such a request instead, because it returns a snapshot URL and cannot return one for a release the repository does not serve:

Output
Repository 'validated-r' serves Bioconductor 3.23 from source 'validated', so it cannot pin Bioconductor version '3.22'

GET /repos/{repo}/sources/{source}/transactions is also where the two repository types differ most visibly. A curated Bioconductor source commits one transaction per release per update, so a Bioconductor repository’s list interleaves every release’s history, and each entry names its own release in bioc_version. An R repository’s list holds only the release it serves.

Disabling the Server API Guide

If you’d like to disable access to the Server API Guide, edit the configuration property [Swagger].Enabled as follows:

/etc/rstudio-pm/rstudio-pm.gcfg
[Swagger]
Enabled = false

For more information, refer to the Swagger configuration settings in the appendix.

Back to top