1. Introduction

This is the documentation of the current minerva API. All endpoints described here are located in the /new_api/ path of the deployed application. For instance, the new API of a project browsed at https://minerva-dev.lcsb.uni.lu/minerva/ is located at https://minerva-dev.lcsb.uni.lu/minerva/new_api/

Note
 The old API, which this one will eventually replace, is documented in Rest API Documentation.

2. How an operation is described

Every operation starts with an HTTP request section stating the method and the URL of the call, and ends the description of the call with an HTTP response section stating the status code returned when it succeeds. Both are taken from the test that exercises the endpoint, so the identifiers in the URL are the ones of a sample database rather than placeholders.

A call that fails answers instead with one of the status codes listed in Errors and with the error body described there.

The remaining sections are present when they apply to the operation: Path Parameters, Query Parameters, Request Fields and Request Parts describe what is sent, Response Fields and Sample Response describe what comes back, and CURL sample shows the whole call as a command that can be copied.

3. QuickStart guide

Endpoints that do not require any privileges can be called right away. This lists the projects visible to an anonymous user:

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/projects/'

Everything else must be called with the rights of a specific user. To do that, create an access token once and send it in the Authorization header of every subsequent request. The token carries the privileges of the user it was created for, so a request made with it can do exactly what that user can do - keep it secret and treat it like a password.

3.1. Step 1 - create an access token

Log in to the minerva web interface and create an access token in your user panel. Give it a name that says what it is used for and an expiration date (at most one year from now). Copy the token value that is shown - this is the only thing the API needs. Tokens can also be created, listed and revoked through the API itself; see the tokens endpoints.

3.2. Step 2 - call the API with the token

Send the token as a Bearer value in the Authorization header:

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/projects/' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...'

The same header works for every endpoint in this documentation, including the ones that modify data:

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/projects/my_project/readonly' \
    -X PUT \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...' \
    -H 'Content-Type: application/json' \
    --data '{"readonly": true}'

A 401 response means the token is unknown to the server, expired, revoked or malformed; the reason field of the error response says which. A 403 response means the token is valid, but the user it belongs to is not allowed to perform the request. A token that is no longer needed should be revoked; see the tokens endpoints. NOTE: Access tokens are the recommended way for scripts and plugins. Interactive clients that log a user in and out instead use the short-lived access token issued during login, which is sent in the very same Authorization: Bearer header and is kept alive through the authentication endpoints.

4. Paging

Every operation that returns a collection returns it one page at a time. The response is an object, not a bare array: content holds the entries of the page, number and size repeat the page that was served, and totalElements and totalPages describe the whole result.

Which page is served is chosen with two optional query parameters:

page

index of the page, counted from 0; 0 by default.

size

number of entries on a page; 20 by default. The largest accepted value is 10000, and a request asking for more than that is served a page of 10000 entries.

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/projects/my_project/maps/?page=1&size=5' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...'

{
  "content": [ ... ],
  "number": 1,
  "size": 5,
  "numberOfElements": 5,
  "totalElements": 42,
  "totalPages": 9
}

Asking for a page beyond the end of the result is not an error - the response is 200 with an empty content and the same totalElements.

Every paged operation is marked in this documentation with a note pointing back to this section.

5. Concurrent modifications

Every entity served by this API carries a version that changes whenever the entity is modified. A response that returns a single entity sends that version in the standard ETag header (collection responses do not carry one):

$ curl -i 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/projects/my_project' \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...'

HTTP/1.1 200 OK
ETag: "7"
Content-Type: application/json
...

To make a modification conditional, send that value back, verbatim and including the quotes, in an If-Match header:

$ curl 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/projects/my_project' \
    -X PUT \
    -H 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9...' \
    -H 'If-Match: "7"' \
    -H 'Content-Type: application/json' \
    --data '{"projectId": "my_project", ...}'

If somebody else modified the entity in the meantime its version is no longer 7, the request is rejected with 412 and nothing is changed. The usual reaction is to fetch the entity again, reapply the change on top of the fresh state and retry with the new ETag.

The header is optional. A request sent without it is unconditional and simply overwrites whatever is stored - the last write wins. Besides a single entity tag, the header accepts a comma separated list of them, matching when any one of them does, and *, matching any existing entity. A weak entity tag (one prefixed with W/) never matches, because If-Match is compared strongly.

Every operation that accepts the header is marked in this documentation with a note pointing back to this section; an operation without that note ignores If-Match.

6. Errors

A request that fails is answered with a status code in the 4xx or 5xx range and with a body that is the same for every operation of this API:

error

short description of what went wrong, the same text for every occurrence of the same kind of failure.

reason

details of this particular failure, meant to be read by a human - the name of the object that was not found, the field that did not validate, and so on.

errorId

identifier of the stacktrace stored by the server; present in a 500 response only. The stacktrace itself is not returned - it can be fetched with the stacktraces endpoint and attached to a bug report.

$ curl -i 'https://minerva-dev.lcsb.uni.lu/minerva/new_api/stacktraces/no_such_stacktrace'

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": "Object not found.",
  "reason": "Object does not exist"
}

These are the status codes the API answers with:

400

the request itself is wrong - a field failed validation, a parameter is missing or has a value the operation does not accept, or the body could not be parsed.

401

the request was not authenticated - it carries no token, or one that is unknown, expired, revoked or malformed.

403

the request was authenticated, but the user it belongs to is not allowed to perform it; an anonymous user gets this for every operation requiring a logged in user.

404

the addressed resource does not exist.

405

the resource exists, but not for the method that was used.

409

the request conflicts with the current state - the object to be created already exists, the resource is not in a state allowing the operation, or another query modified it at the same time.

412

the If-Match header was sent and the entity has been modified in the meantime; see Concurrent modifications.

415

the Content-Type of the request is not supported by the operation.

424

an external service the operation depends on failed.

500

the request failed because of a bug or a misconfiguration of the server; the response carries errorId.

An error is not documented per operation: any operation can answer with 400, 401, 403 or 500, and the ones addressing a resource by its identifier can answer with 404.

7. Projects

Projects and everything nested inside them: maps, bio entities, layers, overlays, comments.
See full documentation.

8. Users

Users, their privileges, authentication and access tokens.
See full documentation.

8.1. Authentication

Logging in returns a short-lived access token, sent as Authorization: Bearer <token> on every subsequent call, plus a long-lived refresh token used to obtain a new access token without logging in again; these endpoints refresh that pair and revoke a refresh token to log out.
See full documentation.

8.2. Tokens

Long lived API tokens that let a script call the API with the rights of a single user.
See full documentation.

9. Plugins

Plugins are external JavaScript extensions, identified by a hash of their code and downloaded from a registered URL, that the map viewer loads for one, several or all projects.
See full documentation.

10. Annotation

Annotators and the external vocabularies used for annotating map elements.
See full documentation.

10.1. Annotators

Annotators query external databases (e.g. UniProt, ChEBI, HGNC) to attach identifiers and cross-references to map elements; this lists the available annotator types and which element types each one can annotate.
See full documentation.

10.2. MeSH

Resolves MeSH identifiers attached to map elements to their Medical Subject Headings vocabulary terms.
See full documentation.

10.3. Taxonomy

Lookup of NCBI taxonomy entries used to annotate organisms.
See full documentation.

11. Permalinks

Stable links that preserve a particular view configuration of a map.
See full documentation.

12. Configuration

Named instance-wide settings, such as the outgoing mail server, LDAP and ORCID login, branding logos and the default map, listed and updated as key/value pairs.
See full documentation.

13. Platform

Instance level operations: file uploads, background jobs, status and diagnostics.
See full documentation.

13.1. Converter

Converts uploaded files between systems biology network formats, renders them as images, and merges several maps into one.
See full documentation.

13.2. Jobs

Status tracking for long running background jobs.
See full documentation.

13.3. Files

Chunked upload of files to the server.
See full documentation.

13.4. Status

Health and version information about the running instance.
See full documentation.

13.5. Stacktraces

Retrieval of stack traces recorded for server side errors.
See full documentation.

13.6. MinervaNet

Forwarding of error reports to the MinervaNet error tracking service.
See full documentation.

14. References

Read only reference data served by the instance.
See full documentation.

14.1. Licenses

Licenses that can be assigned to maps.
See full documentation.

14.2. Data types and formats

Lists of the various types (identifiers, map formats, image formats, overlay types) supported by the instance.
See full documentation.