Difference between revisions of "Ontology Data Service API"

From phenoscape
(→‎Data exchange formats)
(→‎References)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
==Overview==
+
''This is a legacy high-level specification of a common programmatic API needed by EQ editors (such as [[Phenex]] and [http://phenote.org Phenote]) to interface with ontology (and phenotype) repositories. It resulted from a breakout group, consisting of C. Mungall, J. Balhoff, and H. Lapp, of the [[Fish Evolution Working Group]] at their last meeting in November 2006, and served as part of the early input to the web-service design of the Bioportal.''
  
−
Data services have been implemented as part of the Phenoscape application to retrieve data about evolutionary and model organism phenotypes. Ancillary services function in the auto completion of partially entered search terms by retrieving matching terms from the database, query relevant summary information on search terms, and retrieve any stored homology information about the search terms. This page details the functioning of each of these services, which make up the very first implementation of the Phenoscape application.  
+
''This specification as such has not been implemented in the [http://kb.phenoscape.org Phenoscape Knowledgebase] (KB), though some functions proposed here are among the implemented [[Data Services]] (for example "Look up term" as [[Data Services#Term info| Term Info]] and "Completion list" as [[Data Services#Autocomplete| Autocomplete]]. Also, the Bioportal meanwhile has a [http://www.bioontology.org/wiki/index.php/NCBO_REST_services full-featured REST API] that does implement all of the ontology-specific functions enumerated below, and the Phenoscape KB [[Data Services]] implement a much richer set of phenotype annotation services than envisioned below (albeit read-only).''
 +
 
 +
==Goal and motivation==
 +
 
 +
A common API implemented by ontology data services enables clients such as EQ editors that heavily rely on such a service to plug into different data providers, local or remote, at their choice.
  
 
==Service definitions==
 
==Service definitions==
  
−
===Basic Data Services===
+
===Ontology Data Service===
  
−
# Auto completion service
+
# Ontology listing lookup
 +
#* Function: lookup the ontologies being served by the data service
 +
#* Input: none, or a particular name, and/or the name of the ontology category
 +
#* Output: a record of name, version, identifier, meta-data (e.g., retired? in production? purpose?) for each ontology being served
 +
# Look up term
 +
#* Function: Obtain the full term information for a given ID
 +
#* Input: a term ID, or the combination of a term name and ontology ID
 +
#* Output: the matching term in OBO or RDF/OWL format
 +
#* Notes: do we need neighborhood here too (e.g., with IDs only); OBO only has parents, not children.
 +
# Completion list
 
#* Function: Obtain matching term names for a partial term name string
 
#* Function: Obtain matching term names for a partial term name string
−
#* Input: partial term name string, a list of ontology IDs, search parameters (search names only or synonyms only or both)
+
#* Input: partial term name string, a list of ontology IDs, search parameters (search names only or synonyms only or both, search obsoletes or not, search definition or not)
−
#* Output: matches as records of term name or synonym that was hit, and how the term was hit (name or synonym)
+
#* Output: matches as records of term name, term ID, ontology ID, synonym that was hit, how the term was hit (name, synonym, or definition)
−
# Term info service
+
# Neighborhood graph
−
#* Function: Obtain the full term information for a given term
+
#* Function: Obtain parents, children, descendants, or ancestors for a given term
−
#* Input: a term ID
+
#* Input: term ID, list of relationships to include or exclude, number of levels (path length) up and down to include
−
#* Output: the definition and synonyms for the term. In addition, all the parent and child terms of this term are returned. For terms from the Teleost Taxonomy Ontology, their rank and extant/extinct information are returned as well.
+
#* Output: list of terms in OBO or RDF format
−
#Homology information service
+
#* Note: Is it sensible to return a graph as OBO format? Do we need to mandate the semantics of matching mixed-type paths (e.g., is-a and part-of)?
−
#* Function: Obtain homology information for the given anatomical entity. This is applicable only for anatomical entities
+
# Downloading ontology
−
#* Input: term ID for the anatomical entity
+
#* Function: Obtain all terms and relationships comprising an ontology
−
#* Output: homology information for the given entity, with references and evidence codes
+
#* Input: ontology ID, optionally name of the slim
 +
#* Output: the ontology as an OBO or OWL stream of text
 +
#* Notes: do we need a parameter for specifying the desired format? do we need parameter for including obsoletes or not
 +
# SPARQL endpoint
 +
#* Function: Issue SPARQL queries and obtain the results in RDF
 +
#* Input:
 +
#* Output:
 +
 
 +
'''Notes applicable to all:'''
 +
* Do we need to add search parameter to specify the 'slim' for each service that involves specifying an ontoloy?
 +
* Should we have a protocol for client and server negotiating the desired return format, or should this be a parameter (in which case we also need a method to obtain all supported formats from the server)?
  
 
===Phenotype Data Service===
 
===Phenotype Data Service===
  
−
# Phenotype summary service
+
# Login
−
#* Function: For a given anatomical entity, taxon, or gene, retrieve a summary of all annotated phenotypes involving the search term
+
#* Function: Given a username and secret, obtain an authentication token
−
#* Input: A UID for an anatomical entity, taxon, or gene
+
#* Input:
−
#* Output: A summary of all the phenotypes the given anatomical entity, taxon, or gene is involved in. Phenotypes are categorized by anatomical entity-character (EC) combinations. For each EC combination, the numbers of taxa and genes associated with it are returned
+
#* Output:
−
# Phenotype details service
+
# Save EQ statements
−
#* Function: For a given anatomical entity, gene, or taxon, retrieve the details of all the phenotypes it is involved in
+
#* Function: Save an array of EQ statements to the data store
−
#* Input: A UID for an anatomical entity, taxon, or gene
+
#* Input: a list of EQ statements on OBD-xml or pheno-xml format
−
#* Output: A listing of all the Entities and Qualities (EQ) the search term in involved in. The output can be either a listing of genes, or a listing of taxa, or both. For taxa lists, the service creates a taxonomical hierarchy rooted at the Most Recent Common Ancestor (MRCA) of all the taxa, with corresponding listings of EQ combinations at each level and node of the tree. At the leaf level, where the EQ combinations are directly asserted, the service also provides citation information such as the paper from which the assertion was derived, along with character comments, text, and state comments and text
+
#* Output: success/failure indicator
 +
# Load EQ statements
 +
#* Function: Load an array of EQ statements from the data store
 +
#* Input: author, or list of taxa,
 +
#* Output: matching EQ statements in pheno-xml or pheno-syntax format
 +
#* Notes: do we need parameter of list of entities to obtain EQs for?
 +
 
 +
===Query languages===
 +
 
 +
* SPARQL
  
 
===Data exchange formats===
 
===Data exchange formats===
  
 
* Plain text over HTTP:
 
* Plain text over HTTP:
 +
** OBO format
 +
** YAML
 
** JSON
 
** JSON
 +
 +
* XML over HTTP:
 +
** OBO-XML format
 +
** OBD-XML format
 +
 +
* RDF over HTTP:
 +
** RDF/XML
 +
** RDF/N-triples
  
 
==Other ontology service definitions==
 
==Other ontology service definitions==
  
−
* [http://www.ebi.ac.uk/ontology-lookup/ Ontology Lookup Service (OLS)] at the EBI. <cite>cote2006</cite> According to the website, the OLS can integrate any ontology available in OBO format. OLS is implemented as a web-service. The website has documentation on
+
* [http://www.ebi.ac.uk/ontology-lookup/ Ontology Lookup Service (OLS)] at the EBI<ref><pubmed>16507094</pubmed></ref>. According to the website, the OLS can integrate any ontology available in OBO format. OLS is implemented as a web-service. The website has documentation on
 
**  [http://www.ebi.ac.uk/ontology-lookup/WSDLDocumentation.do web-service API] (representing the WSDL) with [http://www.ebi.ac.uk/ontology-lookup/api/uk/ac/ebi/ook/web/interfaces/QueryImpl.html JavaDoc for the interface contract], and
 
**  [http://www.ebi.ac.uk/ontology-lookup/WSDLDocumentation.do web-service API] (representing the WSDL) with [http://www.ebi.ac.uk/ontology-lookup/api/uk/ac/ebi/ook/web/interfaces/QueryImpl.html JavaDoc for the interface contract], and
 
** [http://www.ebi.ac.uk/ontology-lookup/implementationOverview.do implementation overview] (architecture)
 
** [http://www.ebi.ac.uk/ontology-lookup/implementationOverview.do implementation overview] (architecture)
Line 52: Line 94:
 
** The Zthes profile for SRU is based on an [http://zthes.z3950.org/model/zthes-model-1.0.html abstract model for thesaurus representation], which is also available as an XML Schema implementation.
 
** The Zthes profile for SRU is based on an [http://zthes.z3950.org/model/zthes-model-1.0.html abstract model for thesaurus representation], which is also available as an XML Schema implementation.
  
 +
==Next Steps==
  
 +
# Finalize list of services for the ontology data service API.
 +
#* This will be an initial revision 1.0 - we'll surely have iterations later down the road.
 +
#* We'll need an acronym - anyone had a flash of creativity? What about OBODS
 +
# Define which services are mandatory, and which are optional.
 +
# Decide on protocol and query syntax.
 +
#* What about using REST, e.g., http://onto.myorg.edu/obods?q=list_ontology&category=anatomy, or using paths http://onto.myorg.edu/obods/ontology/list?category=anatomy)
 +
# Create a reference implementation for the server.
 +
#* A very generic reference implementation would be a wrapper over a SPARQL endpoint, i.e., translating API calls into SPARQL queries and transforming returned RDF into the required format.
 +
# Create a reference implementation for a web-application client (using JavaScript) and for, e.g., a Java client (for servlets or Java stand-alone apps).
  
 
==References==
 
==References==
  
−
<biblio>
+
<references />
−
#cote2006 pmid=16507094
 
−
</biblio>
 
  
 
[[Category:Informatics]]
 
[[Category:Informatics]]
 
[[Category:API]]
 
[[Category:API]]

Latest revision as of 20:41, 20 September 2011

This is a legacy high-level specification of a common programmatic API needed by EQ editors (such as Phenex and Phenote) to interface with ontology (and phenotype) repositories. It resulted from a breakout group, consisting of C. Mungall, J. Balhoff, and H. Lapp, of the Fish Evolution Working Group at their last meeting in November 2006, and served as part of the early input to the web-service design of the Bioportal.

This specification as such has not been implemented in the Phenoscape Knowledgebase (KB), though some functions proposed here are among the implemented Data Services (for example "Look up term" as Term Info and "Completion list" as Autocomplete. Also, the Bioportal meanwhile has a full-featured REST API that does implement all of the ontology-specific functions enumerated below, and the Phenoscape KB Data Services implement a much richer set of phenotype annotation services than envisioned below (albeit read-only).

Goal and motivation

A common API implemented by ontology data services enables clients such as EQ editors that heavily rely on such a service to plug into different data providers, local or remote, at their choice.

Service definitions

Ontology Data Service

  1. Ontology listing lookup
    • Function: lookup the ontologies being served by the data service
    • Input: none, or a particular name, and/or the name of the ontology category
    • Output: a record of name, version, identifier, meta-data (e.g., retired? in production? purpose?) for each ontology being served
  2. Look up term
    • Function: Obtain the full term information for a given ID
    • Input: a term ID, or the combination of a term name and ontology ID
    • Output: the matching term in OBO or RDF/OWL format
    • Notes: do we need neighborhood here too (e.g., with IDs only); OBO only has parents, not children.
  3. Completion list
    • Function: Obtain matching term names for a partial term name string
    • Input: partial term name string, a list of ontology IDs, search parameters (search names only or synonyms only or both, search obsoletes or not, search definition or not)
    • Output: matches as records of term name, term ID, ontology ID, synonym that was hit, how the term was hit (name, synonym, or definition)
  4. Neighborhood graph
    • Function: Obtain parents, children, descendants, or ancestors for a given term
    • Input: term ID, list of relationships to include or exclude, number of levels (path length) up and down to include
    • Output: list of terms in OBO or RDF format
    • Note: Is it sensible to return a graph as OBO format? Do we need to mandate the semantics of matching mixed-type paths (e.g., is-a and part-of)?
  5. Downloading ontology
    • Function: Obtain all terms and relationships comprising an ontology
    • Input: ontology ID, optionally name of the slim
    • Output: the ontology as an OBO or OWL stream of text
    • Notes: do we need a parameter for specifying the desired format? do we need parameter for including obsoletes or not
  6. SPARQL endpoint
    • Function: Issue SPARQL queries and obtain the results in RDF
    • Input:
    • Output:

Notes applicable to all:

  • Do we need to add search parameter to specify the 'slim' for each service that involves specifying an ontoloy?
  • Should we have a protocol for client and server negotiating the desired return format, or should this be a parameter (in which case we also need a method to obtain all supported formats from the server)?

Phenotype Data Service

  1. Login
    • Function: Given a username and secret, obtain an authentication token
    • Input:
    • Output:
  2. Save EQ statements
    • Function: Save an array of EQ statements to the data store
    • Input: a list of EQ statements on OBD-xml or pheno-xml format
    • Output: success/failure indicator
  3. Load EQ statements
    • Function: Load an array of EQ statements from the data store
    • Input: author, or list of taxa,
    • Output: matching EQ statements in pheno-xml or pheno-syntax format
    • Notes: do we need parameter of list of entities to obtain EQs for?

Query languages

  • SPARQL

Data exchange formats

  • Plain text over HTTP:
    • OBO format
    • YAML
    • JSON
  • XML over HTTP:
    • OBO-XML format
    • OBD-XML format
  • RDF over HTTP:
    • RDF/XML
    • RDF/N-triples

Other ontology service definitions

Next Steps

  1. Finalize list of services for the ontology data service API.
    • This will be an initial revision 1.0 - we'll surely have iterations later down the road.
    • We'll need an acronym - anyone had a flash of creativity? What about OBODS
  2. Define which services are mandatory, and which are optional.
  3. Decide on protocol and query syntax.
  4. Create a reference implementation for the server.
    • A very generic reference implementation would be a wrapper over a SPARQL endpoint, i.e., translating API calls into SPARQL queries and transforming returned RDF into the required format.
  5. Create a reference implementation for a web-application client (using JavaScript) and for, e.g., a Java client (for servlets or Java stand-alone apps).

References

  1. ↑

    Richard G Côté, Philip Jones, Rolf Apweiler, Henning Hermjakob
    The Ontology Lookup Service, a lightweight cross-platform tool for controlled vocabulary queries.
    BMC Bioinformatics: 2006, 7;97
    [PubMed:16507094] [WorldCat.org] [DOI] (I e)

Retrieved from "https://wiki.phenoscape.org/wg/phenoscape/index.php?title=Ontology_Data_Service_API&oldid=8922"