Ontology Data Service API
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
- 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
- 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)
- 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)?
- 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
- 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
- Login
- Function: Given a username and secret, obtain an authentication
token
- Input:
- Output:
- 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
- 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
- XML over HTTP:
- OBO-XML format
- OBD-XML format
Other ontology service definitions
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.
- 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
