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 tototalPages
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 tototalPages
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 tototalPages
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 profileprefix
a booleantrue
orfalse
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, onlyPRINCIPAL_INVESTIGATOR
is currently supportedresearcherCategories
a set of researcher category likeIN_SILICO
orIN_VITRO
organUberonIds
a set of Uberon identifiers that the user has added to its profile as organ systemsontologyNames
andontologyTermIds
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 symboltaxonId
a taxon identifier in which the search is performedorthologTaxonId
an ortholog taxon identifier, omitting it searches all taxatier
a single tier to filter by (deprecated as of 1.4.0 in favour oftiers
)tiers
a set of tiers includingTIER1
,TIER2
andTIER3
Then any of the following as described in "Search users":
researcherPositions
researcherCategories
organUberonIds
ontologyNames
andontologyTermIds
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.