REST API overview¶
Everything the openPIP web interface does goes through a JSON REST API, and the same API is open to your own scripts. This section documents every endpoint the server provides. A test in the backend suite compares this reference with the server's URL configuration, so an endpoint cannot be added or removed without this reference failing that test.
For bulk interaction data in a standard format, also see the PSICQUIC service, which speaks the protocol used by IntAct, BioGRID and other interaction databases.
Base URL¶
All paths in this reference are relative to the portal's address, so on this
portal GET /api/search means:
Example responses are real, taken from the reference portal at openpip.usask.ca, which hosts the Human Reference Interactome datasets. Another portal returns its own data in the same shape.
Trailing slashes¶
Most paths have no trailing slash. Paths are matched exactly, so
/api/search/ returns 404. The exceptions, which require a trailing slash,
are written with one in this reference: /api/schema/, /api/docs/,
/api/datasets/download/, /api/upload/, and the saved views, shares and
notifications endpoints. Without the slash, the server answers with a 301
redirect to the slashed path. That is harmless for GET, but most HTTP
clients repeat a redirected POST as a GET without its body, so always send
POST, PUT, PATCH and DELETE to the exact path shown.
Authentication¶
Public data needs no authentication. Searching, protein and dataset details, downloads and PSICQUIC all work anonymously.
Personal endpoints (saved networks, sharing, profiles) and administrative endpoints need a login token, sent as a header:
Get tokens from POST /api/auth/login.
An access token lasts 1 hour. Use the refresh token, which lasts 7 days, to
get a new pair from
POST /api/auth/token/refresh.
Note
If you send an Authorization header with an expired or invalid token, the
request fails with 401 even on public endpoints. Omit the header for
anonymous requests.
Administrative endpoints additionally require the account to be a site administrator. A request from any other account gets 403.
Errors¶
Errors use HTTP status codes with a JSON body. Most bodies have a single
detail message:
Validation errors name the offending fields instead:
| Status | Meaning |
|---|---|
| 400 | The request is invalid. The body says why. |
| 401 | No valid login token was sent and the endpoint needs one, or the token sent is invalid or expired. |
| 403 | You are logged in but not allowed to do this, usually because it is admin-only. |
| 404 | No such object, or an object you may not see. |
| 429 | Rate limit exceeded. The body says how many seconds to wait. |
PSICQUIC errors are plain text, not JSON. See the PSICQUIC page.
Rate limits¶
| Caller | Limit |
|---|---|
| Anonymous, per IP address | 600 requests per minute |
| Logged in, per account | 1,200 requests per minute |
| PSICQUIC, per IP address, or per account when logged in | 60 requests per minute |
| Security-question answers, per IP address, or per account when logged in | 10 per hour |
| Security-question answers about any one email address, from everyone combined | 10 per hour |
A request over the limit gets 429.
Pagination¶
Only one endpoint is paginated:
GET /api/proteins takes limit and
offset. Every other list returns all its results in one response. Lists that
could grow large are bounded: search returns the networks for the proteins you
ask for, notifications return the newest 50, and user search returns at most
10 matches.
Cross-origin requests¶
The API and PSICQUIC accept browser requests from any origin (CORS). Login tokens are sent in a header, not as cookies, so a third-party page cannot act for a logged-in user.
Machine-readable schema¶
GET /api/schema/¶
An OpenAPI 3 schema generated from the code, as YAML. Add ?format=json for
JSON. No authentication.
The generated schema is incomplete
The schema lists every path and method, but for most endpoints it does not describe the request parameters or the response. Those endpoints are written in a style the generator cannot inspect. Use this reference for request and response details.
GET /api/docs/¶
An interactive Swagger UI page for the schema above. It loads its scripts from the jsDelivr CDN.