PhenoTips » Developer Guide » API » Suggested Gene Panels RESTfulAPI

Suggested Gene Panels RESTfulAPI

This page is a draft.

Starting with version 1.3 Milestone 6 PhenoTips provides a RESTful API ability to retrieve suggested gene panels.
The REST services allow listing suggested gene panels for a given list of phenotypes, as well as for a specific patient. Data is exchanged in JSON format. 

Resources

Resource URIs are specified using URI templates. Bracketed elements are formal parameters and should be instantiated to actual values in order to retrieve the associated resource.

Root resources

/suggested-gene-panels?present-term={present-term}[&startPage={startPage}][&numResults={numResults}[&reqNo={reqNo}]

  • HTTP Method: POST

    Content type:
    application/x-www-form-urlencoded
    Result: 
    Provides gene suggestions based on an input for the specified phenotypes. Request can optionally specify additional filters. If no suggestions are found an empty response is returned.
    Parameters:
    present-term  An ID for a phenotypic term that is present
    startPage  The start page for pagination. If start page is out of bounds, will result in response code 400.
    numResults  The number of results per page. If this is not specified, or if a negative integer is entered, the "startPage" parameter is ignored, and all the results are returned.
    reqNo  The number of the request.
    Status codes:
    200 if request was successful and data is available
    204 if no "present-term" nor "absent-term" are provided, or if there is no content associated with the provided terms
    500 in the event of any unexpected error

Patient resources

/patients/{id}/suggested-gene-panels

  • HTTP method: GET

    Media type:
    application/json
    Result:
    Retrieves a suggested genes based on phenotypes of a patient identified by given identifier in its JSON representation. If the indicated patient record doesn't exist, or if the user sending the request doesn't have the right to view the target patient record, an error is returned. 
    Status codes:
    200 if request was successful
    401 if the user was not authenticated
    403 if the user was authenticated but not authorized 
    404 if the resource was not found

Basic examples using a REST client

The example uses a root URI running a PhenoTips instance locally on port 8080:

http://localhost:8080/rest/suggested-gene-panels
 

List suggested genes based on present phenotypes

HTTP method: POST
URL: http://localhost:8080/rest/suggested-gene-panels?present-term={present-term}[&startPage={startPage}][&numResults={numResults}[&reqNo={reqNo}]

For a present phenotypic term with a value of HP:0200029, replace {present-term} in the url with HP:0200029.

Example httpie request:

http --session=JohnDoe GET http://localhost:8080/rest/suggested-gene-panels?present-term=HP:0200029

Example curl request:

curl -H "Content-Type: application/x-www-form-urlencoded" -X POST http://localhost:8080/rest/suggested-gene-panels?present-term=HP:0200029

Example response body:

{
"totalSize": 2,
"size": 2,
"genes": [{
"terms": [{
"score": 9.724207,
"synonym": ["Cutaneous vasculitis"],
"xref": ["SNOMEDCT_US:53312001", "UMLS:C0262988"],
"name_translated": "Vasculitis in the skin",
"name": "Vasculitis in the skin",
"term_category": ["HP:0200029", "HP:0002633", "HP:0011276", "HP:0025015", "HP:0002597", "HP:0011354", "HP:0001626", "HP:0011121", "HP:0000118", "HP:0000951", "HP:0000001", "HP:0001574"],
"id": "HP:0200029",
"is_a": ["HP:0002633", "HP:0011276"],
"associated_genes": ["PGM3", "TREX1"],
"parents": [{
"name_translated": "Vasculitis",
"name": "Vasculitis",
"id": "HP:0002633"
}, {
"name_translated": "Vascular skin abnormality",
"name": "Vascular skin abnormality",
"id": "HP:0011276"
}]
}],
"gene_symbol": "TREX1",
"count": 1,
"gene_id": "ENSG00000213689"
}, {
"terms": [{
"score": 9.724207,
"synonym": ["Cutaneous vasculitis"],
"xref": ["SNOMEDCT_US:53312001", "UMLS:C0262988"],
"name_translated": "Vasculitis in the skin",
"name": "Vasculitis in the skin",
"term_category": ["HP:0200029", "HP:0002633", "HP:0011276", "HP:0025015", "HP:0002597", "HP:0011354", "HP:0001626", "HP:0011121", "HP:0000118", "HP:0000951", "HP:0000001", "HP:0001574"],
"id": "HP:0200029",
"is_a": ["HP:0002633", "HP:0011276"],
"associated_genes": ["PGM3", "TREX1"],
"parents": [{
"name_translated": "Vasculitis",
"name": "Vasculitis",
"id": "HP:0002633"
}, {
"name_translated": "Vascular skin abnormality",
"name": "Vascular skin abnormality",
"id": "HP:0011276"
}]
}],
"gene_symbol": "PGM3",
"count": 1,
"gene_id": "ENSG00000013375"
}],
"totalPages": 1
}