PhenoTips » Developer Guide » API » Vocabularies RESTful API

Vocabularies RESTful API

This page is a draft.

Starting with version 1.3 Milestone 1 PhenoTips provides a RESTful API ability to retrieve and reindex vocabularies.

The REST services allow listing and reindexing existing vocabularies, as well as retriveing vocabulary term or getting the list of suggestions for given vocabulary term. Data is exchanged in JSON format. 

The following standard vocabularies are currently supported:

  • HUGO GENE NOMENCLATURE COMMITTEE'S GENENAMES (HGNC)
    HGNC Database, HUGO Gene Nomenclature Committee (HGNC), EMBL Outstation - Hinxton, European Bioinformatics Institute, Wellcome Trust Genome Campus, Hinxton, Cambridgeshire, CB10 1SD, UK
  • CHEMICAL ENTITIES OF BIOLOGICAL INTEREST (CHEBI)
    The ChEBI reference database and ontology for biologically relevant chemistry: enhancements for 2013. Hastings, J., de Matos, P., Dekker, A., Ennis, M., Harsha, B., Kale, N., Muthukrishnan, V., Owen, G., Turner, S., Williams, M., and Steinbeck, C. (2013). Nucleic Acids Res.
  • THE HUMAN PHENOTYPE ONTOLOGY (HPO)
    The Human Phenotype Ontology project: linking molecular biology and disease through phenotype data. Sebastian Köhler, Sandra C Doelken, Christopher J. Mungall, Sebastian Bauer, Helen V. Firth, et al. Nucl. Acids Res. (1 January 2014) 42 (D1): D966-D974 doi:10.1093/nar/gkt1026
  • ONLINE MENDELIAN INHERITANCE IN MAN (OMIM)
    Online Mendelian Inheritance in Man, OMIM®. McKusick-Nathans Institute of Genetic Medicine, Johns Hopkins University (Baltimore, MD)
  • ORPHANET RARE DISEASE ONTOLOGY (ORDO) , also known as "ORPHA"
    Orphanet: an online database of rare diseases and orphan drugs. Copyright, INSERM 1997. Available at http://www.orpha.net##

One non-standard vocabulary that PhenoTips supports is the ethnicity vocabulary, also known as "ETHNO".

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

/vocabularies

  • HTTP method: GET

    Media types (must request one with the “Accept” HTTP request header):
    application/json
    application/xml
    Result:
    List the available vocabularies in this PhenoTips instance
    Status codes:
    200 if request was successful
    500 if an unknown error occured

Vocabulary Resources

/vocabularies/{vocabulary}

  • HTTP Method: GET

    Media types (must request one with the “Accept” HTTP request header):
    application/json
    application/xml
    Result: 
    Retrieves a representation of the specified vocabulary. The vocabulary can be specified by any of its known aliases. i.e /vocabularies/hpo and /vocabularies/HP will retrieve the same resource.

    Status codes:
    200 if request was successful
    404 if no vocabulary was found with the specified id
  • HTTP Method: POST

    Result: 
    Reindex the whole vocabulary, fetching the source from the specified location. Reindexing may take some time to complete. This request must come from an adminstrator.
    Parameters:
    url: The URL to be indexed
    Status codes:
    200 if request was successful
    400 if the request was malformed or the specified url is invalid
    403 if the user does not have administrating rights on PhenoTips
    404 if no vocabulary was found with the specified ID
    500 if the reindexing failed
    503 if the specified vocabulary does not support reindexing
  • HTTP Method: GET

    Result: 
    Provides term suggestions based on an input for the specified Vocabulary. Request can optionally specify additional filters. If no suggestions are found an empty response is returned.
    Parameters:
    input: The string upon which suggestions will be based
    maxResults: The maximum number of results to be returned; Defaults to 10
    sort: an optional sort parameter, in a format that depends on the actual engine that stores the vocabulary. Usually a property name followed by code asc or desc; Usually empty
    customFilter:  custom filter query to further restrict which terms may be returned, in a format that depends on the actual engine that stores the vocabulary; some vocabularies may not support a filter query; May be empty
    Status codes:
    200 if request was successful
    400 if vocabulary or input are empty or malformed
    404 if the vocabulary was not found

/vocabularies/{vocabulary}/{id}

  • HTTP Method: GET

    Result: 
    Retrieves a JSON representation of the vocabulary term by searching the specified vocabulary. The vocabulary may be specified by any of its known aliases. The id can either be in the form of PREFIX:XXXX where the prefix is the vocabulary identifier and the XXXX are replaced by digits.
    Status codes:
    200 if request was successful

/vocabularies/terms/{id}

  • HTTP Method: GET

    Result: 
    Retrieves a JSON representation of the vocabulary term by resolving the vocabulary based on the ID's prefix. The id must be in the form PREFIX:XXXX where the prefix is the vocabulary identifier and the XXXX are replaced by digits.
    Status codes:
    200 if request was successful

Basic examples using a REST client

The examples use a root URI running a PhenoTips instance locally on port 8080:

http://localhost:8080/rest/vocabularies
 

View all vocabularies

HTTP method: GET
URL: http://localhost:8080/rest/vocabularies

With a REST client browser extension, select the HTTP method and fill in the appropriate URL for the request. In this case, we would select GET and input the URL above. 

Example httpie request:

http --session=JohnDoe GET http://localhost:8080/rest/vocabularies

Example curl request:

curl http://localhost:8080/rest/vocabularies

Example response body:

{
 "links": [{
     "allowedMethods": ["GET"],
     "href": "http://localhost:8080/rest/vocabularies",
     "rel": "self"
    },{
     "allowedMethods": ["GET"],
     "href": "http://localhost:8080/rest/"
    }],
 "vocabularies": [{
     "links": [{
         "allowedMethods": ["POST","GET"],
         "href": "http://localhost:8080/rest/vocabularies/ethnicity",
         "rel": "https://phenotips.org/rel/vocabulary"
        },{
         "allowedMethods": ["GET"],
         "href": "http://localhost:8080/rest/vocabularies/ethnicity/suggest",
         "rel": "https://phenotips.org/rel/suggest"
        }],
     "identifier": "ethnicity",
     "name": "Ethnicities (non-standard)",
     "aliases": ["ethnicity","ETHNO"],
     "size": 1242
    },{
     "links": [{
         "allowedMethods": ["POST","GET"],
         "href": "http://localhost:8080/rest/vocabularies/chebi",
         "rel": "https://phenotips.org/rel/vocabulary"
        },{
         "allowedMethods": ["GET"],
         "href": "http://localhost:8080/rest/vocabularies/chebi/suggest",
         "rel": "https://phenotips.org/rel/suggest"
        }],
     "identifier": "chebi",
     "name": "Chemical Entities of Biological Interest (ChEBI)",
     "aliases": ["chebi","CHEBI","ChEBI"],
     "size": 107253,
     "version": "151",
     "defaultSourceLocation": "ftp://ftp.ebi.ac.uk/pub/databases/chebi/ontology/chebi.obo"
    },{
     "links": [{
         "allowedMethods": ["POST","GET"],
         "href": "http://localhost:8080/rest/vocabularies/hgnc",
         "rel": "https://phenotips.org/rel/vocabulary"
        },{
         "allowedMethods": ["GET"],
         "href": "http://localhost:8080/rest/vocabularies/hgnc/suggest",
         "rel": "https://phenotips.org/rel/suggest"
        }],
     "identifier": "hgnc",
     "name": "HUGO Gene Nomenclature Committee's GeneNames (HGNC)",
     "aliases": ["hgnc","HGNC"],
     "size": 42197,
     "version": "2017-05-15T17:13:50.033Z",
     "defaultSourceLocation": "ftp://ftp.ebi.ac.uk/pub/databases/genenames/new/tsv/hgnc_complete_set.txt"
    },{
     "links": [{
         "allowedMethods": ["POST","GET"],
         "href": "http://localhost:8080/rest/vocabularies/hpo",
         "rel": "https://phenotips.org/rel/vocabulary"
        },{
         "allowedMethods": ["GET"],
         "href": "http://localhost:8080/rest/vocabularies/hpo/suggest",
         "rel": "https://phenotips.org/rel/suggest"
        }],
     "identifier": "hpo",
     "name": "The Human Phenotype Ontology (HPO)",
     "aliases": ["hpo","HPO","HP"],
     "size": 12359,
     "version": "releases/2017-04-13",
     "defaultSourceLocation": "https://raw.githubusercontent.com/obophenotype/human-phenotype-ontology/master/hp.obo"
    },{
     "links": [{
         "allowedMethods": ["POST","GET"],
         "href": "http://localhost:8080/rest/vocabularies/omim",
         "rel": "https://phenotips.org/rel/vocabulary"
        },{
         "allowedMethods": ["GET"],
         "href": "http://localhost:8080/rest/vocabularies/omim/suggest",
         "rel": "https://phenotips.org/rel/suggest"
        }],
     "identifier": "omim",
     "name": "Online Mendelian Inheritance in Man (OMIM)",
     "aliases": ["MIM","omim","OMIM"],
     "size": 23966,
     "version": "2017-03-14T05:02:32.259Z",
     "defaultSourceLocation": "http://data.omim.org/downloads/???/mimTitles.txt"
    },{
     "links": [{
         "allowedMethods": ["POST","GET"],
         "href": "http://localhost:8080/rest/vocabularies/ordo",
         "rel": "https://phenotips.org/rel/vocabulary"
        },{
         "allowedMethods": ["GET"],
         "href": "http://localhost:8080/rest/vocabularies/ordo/suggest",
         "rel": "https://phenotips.org/rel/suggest"
        }],
     "identifier": "ordo",
     "name": "Orphanet Rare Disease Ontology",
     "aliases": ["Orphanet Rare Disease Ontology","ORPHA","ordo","ORDO"],
     "size": 12583,
     "version": "2.3",
     "defaultSourceLocation": "http://data.bioontology.org/ontologies/ORDO/submissions/10/download?apikey=8b5b7825-538d-40e0-9e9e-5ab9274a9aeb"
    }]
}

View a specific vocabulary

HTTP method: GET
URL: http://localhost:8080/rest/vocabularies/{id}

For a vocabulary term with an id value of HPO, replace {id} in the url with HPO.

Example httpie request:

http --session=JohnDoe GET http://http://localhost:8080/rest/vocabularies/HPO

Example curl request:

curl http:/http://localhost:8080/rest/vocabularies/HPO

Example response body:

{
   "links": [{
           "allowedMethods": ["POST","GET"],
           "href": "http://localhost:8088/rest/vocabularies/HPO",
           "rel": "self"
        },{
           "allowedMethods": [ "GET"],
           "href": "http://localhost:8088/rest/vocabularies/HPO/suggest",
           "rel": "https://phenotips.org/rel/suggest"
        },{
           "allowedMethods": ["GET"],
           "href": "http://localhost:8088/rest/vocabularies",
           "rel": "https://phenotips.org/rel/vocabularies"
        }],
   "identifier": "hpo",
   "name": "The Human Phenotype Ontology (HPO)",
   "aliases": ["hpo","HPO","HP"],
   "size": 12244,
   "version": "releases/2017-01-23",
   "defaultSourceLocation": "https://compbio.charite.de/jenkins/job/hpo/lastStableBuild/artifact/hp/hp.obo"
}

Index a specific vocabulary

HTTP method: POST
URL: http://localhost:8080/rest/vocabularies/{id}

For a vocabulary term with an id value of HPO, replace {id} in the url with HPO.

Example httpie request:

http --session=JohnDoe POST http://http://localhost:8080/rest/vocabularies/HPO

Example curl request:

curl -u Admin:admin -H "Content-Type: application/json" -X POST http://localhost:8080/rest/vocabularies/HPO

View a single vocabulary term

HTTP method: GET
URL: http://localhost:8080/rest/vocabularies/{id}

For a vocabulary term with an id value of HP:0011451, replace {id} in the url with HP:0011451.

Example httpie request:

http --session=JohnDoe GET http://localhost:8080/rest/vocabularies/HP:0011451

Example curl request:

curl http://localhost:8080/rest/vocabularies/terms/HP:0011451

Example response body:

{
   "xref": ["UMLS:C2677180","UMLS:C4020749"],
   "def": "Microcephaly (HP:0000252) that is present already at the time of birth.",
   "name_translated": "Congenital microcephaly",
   "def_translated": "Microcephaly (HP:0000252) that is present already at the time of birth.",
   "term_category": ["HP:0011451","HP:0000252","HP:0007364","HP:0040195","HP:0002060","HP:0002977","HP:0000240","HP:0100547","HP:0002011","HP:0000929","HP:0012443","HP:0012639","HP:0000234","HP:0009121","HP:0000707","HP:0000152","HP:0011842","HP:0000118","HP:0000924","HP:0000001"],
   "score": 9.724207,
   "synonym": [
       "Congenital decreased head circumference",
       "Congenital small head",
       "Congenital small head circumference",
       "Congenital small skull",
       "Decreased head circumference present at birth",
       "Head circumference small for gestational age",
       "Microcephaly present at birth",
       "Small cranium present at birth",
       "Small head circumference present at birth",
       "Small head present at birth",
       "Small skull present at birth"
    ],
   "name": "Congenital microcephaly",
   "links": [{
           "rel": "self",
           "href": "http://localhost:8088/rest/vocabularies/HPO/HP:0011451",
           "allowedMethods": ["GET"]
        },{
           "rel": "https://phenotips.org/rel/vocabulary",
           "href": "http://localhost:8088/rest/vocabularies/HPO",
           "allowedMethods": ["POST","GET"]
        }],
   "id": "HP:0011451",
   "is_a": ["HP:0000252"],
   "associated_genes": ["PHGDH","RBBP8"],
   "parents": [{
           "name_translated": "Microcephaly",
           "name": "Microcephaly",
           "id": "HP:0000252"
        } ]
}

View term suggestions

HTTP method: GET
URL: /vocabularies/{vocabulary}/suggest?input={input}[[&maxResults={maxResults}][&sort={sort}][&customFilter={customFilter}]]

For a vocabulary with an {vocabulary} value of HPO, replace {vocabulary} in the url with HPO, and for suggestions input for input of e.g. microcephaly replace {input} with micrcephaly

Example httpie request:

http --session=JohnDoe GET http://localhost:8080/rest/vocabularies/HPO/suggest?input=microcephaly

Example curl request:

curl http://localhost:8080/rest/vocabularies/HPO/suggest?input=microcephaly

Example response body:

{
   "links": [
        {
           "allowedMethods": ["GET"],
           "href": "http://localhost:8088/rest/vocabularies/HPO/suggest?input=microcephaly",
           "rel": "self"
        },{
           "allowedMethods": ["POST","GET"],
           "href": "http://localhost:8088/rest/vocabularies/HPO",
           "rel": "https://phenotips.org/rel/vocabulary"
        }],
   "vocabularyTerms": [{
           "links": [{
                   "allowedMethods": ["GET"],
                   "href": "http://localhost:8088/rest/vocabularies/HPO/HP:0000252",
                   "rel": "https://phenotips.org/rel/vocabularyTerm"
                },{
                   "allowedMethods": ["POST","GET"],
                   "href": "http://localhost:8088/rest/vocabularies/HPO",
                   "rel": "https://phenotips.org/rel/vocabulary"
                }],
           "id": "HP:0000252",
           "name": "Microcephaly",
           "description": "Occipito-frontal (head) circumference (OFC) less than -3 standard deviations compared to appropriate, age matched, normal standards (Ross JJ, Frias JL 1977, PMID:9683597). Alternatively, decreased size of the cranium."
        },{
           "links": [ {
                   "allowedMethods": ["GET"],
                   "href": "http://localhost:8088/rest/vocabularies/HPO/HP:0000253",
                   "rel": "https://phenotips.org/rel/vocabularyTerm"
                },{
                   "allowedMethods": ["POST","GET"],
                   "href": "http://localhost:8088/rest/vocabularies/HPO",
                   "rel": "https://phenotips.org/rel/vocabulary"
                }],
           "id": "HP:0000253",
           "name": "Progressive microcephaly",
           "description": "Progressive microcephaly is diagnosed when the head circumference falls progressively behind age- and gender-dependent norms."
        },{
           "links": [{
                   "allowedMethods": ["GET"],
                   "href": "http://localhost:8088/rest/vocabularies/HPO/HP:0005484",
                   "rel": "https://phenotips.org/rel/vocabularyTerm"
                },{
                   "allowedMethods": ["POST","GET"],
                   "href": "http://localhost:8088/rest/vocabularies/HPO",
                   "rel": "https://phenotips.org/rel/vocabulary"
                }],
           "id": "HP:0005484",
           "name": "Postnatal microcephaly",
           "description": "Microcephaly (HP:0000252) with onset in the postnatal period, that is, the head circumference is in the normal range at birth but falls behind normal values later in development."
        },{
           "links": [{
                   "allowedMethods": ["GET"],
                   "href": "http://localhost:8088/rest/vocabularies/HPO/HP:0011451",
                   "rel": "https://phenotips.org/rel/vocabularyTerm"
                },{
                   "allowedMethods": ["POST","GET"],
                   "href": "http://localhost:8088/rest/vocabularies/HPO",
                   "rel": "https://phenotips.org/rel/vocabulary"
                }],
           "id": "HP:0011451",
           "name": "Congenital microcephaly",
           "description": "Microcephaly (HP:0000252) that is present already at the time of birth."
        },{
           "links": [{
                   "allowedMethods": ["GET"],
                   "href": "http://localhost:8088/rest/vocabularies/HPO/HP:0040196",
                   "rel": "https://phenotips.org/rel/vocabularyTerm"
                },{
                   "allowedMethods": ["POST", "GET"],
                   "href": "http://localhost:8088/rest/vocabularies/HPO",
                   "rel": "https://phenotips.org/rel/vocabulary"
                }],
           "id": "HP:0040196",
           "name": "Mild microcephaly",
           "description": "Decreased occipito-frontal (head) circumference (OFC). For the microcephaly OFC must be between -3 SD and -2 SD compared to appropriate, age matched, normal standards (i.e. -3 SD <= OFC < -2 SD)."
        }]
}