API

RDP provides an extensive RESTful API to perform gene searches, obtain user details, etc.

OpenAPI specification

The OpenAPI specification can be retrieved to get a complete description of the endpoints and accepted parameters.

GET /api HTTP/1.1

CORS

As of 1.5.0, a CORS policy has been established to allow scripts served from the main website to freely access the API endpoints.

In your application.properties, set rdp.site.mainsite to your main website URL:

rdp.site.mainsite=https://example.com

Authentication

Clients can authenticate on any API endpoint using a secret access token attached to their account. This allows them to perform the action with their level of access.

For partner registry administrators, the access can instead be authenticated with the remote admin using one of the token listed in rdp.settings.isearch.auth-tokens as described in the International data customization section.

For external services, authentication should instead be performed with using a service account with a secret access token.

GET /api/** HTTP/1.1
Authorization: Bearer {accessToken}

Passing the authorization token via auth query parameter is deprecated as of 1.4.0.

GET /api/users?auth={accessToken} HTTP/1.1

Keep in mind that the token you use is tied to a user that has permissions. What you can see through the API will be restricted to what the corresponding user is authorized to read.

Anonymized results

If rdp.settings.privacy.enable-anonymized-search-results is set to true, certain results may be anonymized depending on your permissions.

These results will have an anonymousId attribute that can subsequently be used to retrieve the result with elevated privileges via either the user by anonymous ID or gene by anonymous ID endpoint.

The way we envision this is that the user will forward the anonymized ID to a registry administrator which can then mediate the interaction between the two users.

For example, an initial unauthenticated request might return a few anonymized results:

GET /api/users HTTP/1.1
{
  "content": [
    {
      "anonymousId": "7d0aaaa3-e119-4ff1-a280-b0a94d510ab0",
      "email": null,
      "name": "RDP User",
      "...": "..."
    },
    {
      "...": "..."
    }
  ]
}

The get more information about that user, you may perform a request with elevated privileges using a token-based authentication:

GET /api/users/by-anonymous-id/7d0aaaa3-e119-4ff1-a280-b0a94d510ab0 HTTP/1.1
Authorization: Bearer k1j2okjd98e3u1
{
  "id": 113,
  "email": "foo@example.com",
  "...": "..."
}

List all users

List all users in a paginated format.

GET /api/users HTTP/1.1
  • page the page to query starting from zero to totalPages

If rdp.settings.privacy.enable-anonymized-search-results is set to true, anonymized results are included in the output.

List all genes

List all genes in a paginated format.

GET /api/genes HTTP/1.1
  • page the page to query starting from zero to totalPages

If rdp.settings.privacy.enable-anonymized-search-results is set to true, anonymized results are included in the output.

Retrieve a single taxon

Note

New in 1.5.0.

GET /api/taxa/{taxonId} HTTP/1.1

This can be used in conjunction to the statistics endpoint to get more details about taxa retrieved in the researcher count mapping.

List all categories/ontologies

Note

New in 1.5.0.

GET /api/ontologies HTTP/1.1

List all terms in a category/ontology

Note

New in 1.5.0.

GET /api/ontologies/{ontologyName}/terms HTTP/1.1
  • page the page to query starting from zero to totalPages

List specific terms in a category/ontology

Note

New in 1.5.0.

GET /api/ontologies/{ontologyName}/terms?ontologyTermIds HTTP/1.1

To retrieve specific terms, you may use ontologyTermIds query parameter and pass it as many time as you want. The output is not paginated and the page parameter from List all terms in a category/ontology is ignored.

Retrieve a single category/ontology term

Note

New in 1.5.0.

GET /api/ontologies/{ontologyName}/terms/{termId}

Search users

Search users by name or description.

GET /api/users/search HTTP/1.1

By name:

  • nameLike a name in the user profile
  • prefix a boolean true or false whether the name search is matching a prefix

By description:

  • descriptionLike a description in the user profile

By name and description: (new in 1.5.0)

  • nameLike
  • prefix
  • descriptionLike

In any case, you can narrow down the result with the following query parameters:

  • researcherPositions a set of researcher positions, only PRINCIPAL_INVESTIGATOR is currently supported
  • researcherCategories a set of researcher category like IN_SILICO or IN_VITRO
  • organUberonIds a set of Uberon identifiers that the user has added to its profile as organ systems
  • ontologyNames and ontologyTermIds two lists of corresponding ontology names and term IDs (new in 1.5.0)

Warning

If an ontology cannot be retrieved by ontologyNames, a 400 Bad Request status will be emitted in the response. You should use the list all categories/ontologies endpoint prior to supplying terms.

No error will be produced if some of the terms do not exist, however no results will be returned.

Search genes

Search user genes by symbols.

GET /api/genes/search HTTP/1.1
  • symbol a gene symbol
  • taxonId a taxon identifier in which the search is performed
  • orthologTaxonId an ortholog taxon identifier, omitting it searches all taxa
  • tier a single tier to filter by (deprecated as of 1.4.0 in favour of tiers)
  • tiers a set of tiers including TIER1, TIER2 and TIER3

Then any of the following as described in "Search users":

  • researcherPositions
  • researcherCategories
  • organUberonIds
  • ontologyNames and ontologyTermIds two lists of corresponding ontology names and term IDs (new in 1.5.0)

Warning

If an ontology cannot be retrieved by ontologyNames, a 400 Bad Request status will be emitted in the response. You should use the list all categories/ontologies endpoint prior to supplying terms.

No error will be produced if some of the terms do not exist, however no results will be returned.

Find a user by its identifier

Find a user given its real or anonymous identifier.

GET /api/users/{userId} HTTP/1.1

Or anonymously:

GET /api/users/by-anonymous-id/{anonymousId} HTTP/1.1

The anonymous identifier can be obtained by performing a users or genes search and retrieving the anonymousId from its result.

Find a user gene by its anonymous identifier

Note

New in 1.5.0.

Retrieves an anonymized result from a previous user gene search.

GET /api/genes/by-anonymous-id/{anonymousId} HTTP/1.1

Statistics

Obtain a few statistics for the number of registered users, genes, etc.

GET /api/stats HTTP/1.1

Note

The version field was added in 1.5.0. Previously, you had to parse the /api endpoint and extract the version from info.version.

Warning

This endpoint was stabilized in the 1.5.0 release and some of its attributes have been renamed as a result. This is noted in the 1.5 migration notes.

Example output:

{
  "version": "1.5.0",
  "users": 22,
  "publicUsers": 0,
  "usersWithGenes": 4,
  "userGenes": 18,
  "uniqueUserGenes": 18,
  "uniqueUserGenesInAllTiers": 18,
  "uniqueHumanUserGenesInAllTiers": 30,
  "researchersByTaxonId": {
    "4896": 0,
    "7955": 0,
    "559292": 0,
    "10116": 1,
    "9606": 1,
    "10090": 2,
    "7227": 0,
    "8364": 0,
    "6239": 1
  }
}

To obtain more details about the taxon, you may use the taxon endpoint. Note that JSON does not allow integer has keys in a mapping, but those can be safely treated as such.