Resource Index REST Web Service User Guide

From NCBO Wiki
Jump to navigation Jump to search

Introduction

The Resource Index API is available through a REST web services interface.

This documentation describes the current version of the API. Some changes may append in the future.

The Resource index API is based on the web service that returns annotations from the Resource Index (called via a REST post). Additionally some simplified REST get services returned simplified results.

Sample HTTP Client for the Resource Index REST Web Service

Test HTML Page : http://rest.bioontology.org/resource_index/test

Resources Service Page : http://rest.bioontology.org/resource_index/resources/list/

Service endpoint

POST your requests at http://rest.bioontology.org/resource_index/

Web Service Parameters

The Resource Index web service offers a set of parameters that allows a user to customize the annotations returned according to his specific requirements. For example, the annotations returned can be limited to a specific set of ontology and a specific set of semantic types. Plus, the expanded annotations can be filtered.

Please see below for the list of parameters and the possible values.

localOntologyIDs {localOntology1,...,localOntologyN} default: empty (i.e. all ontologies) Specifies the list of ontologies you want to filter in the result from the annotation process. The list of ontologies that can be used is available in the sample HTML page. The values are separated with comma (without spaces)
  • For example, SNOMEDCT,NCI,MSH.
semanticTypes {semanticType1,...,semanticTypeN} default: empty (i.e. all semanticTypes) Specifies the list of semantic types to use in the annotation process. The list of semantic types that can be used is available at the /obs/semanticTypes URL. Note that the restriction to semantic types is also applied during the semantic expansion steps.
  • For example, T047,T048,T191.
levelMin and levelMax {integer} default: 0 Specifies the minimum (resp. maximum) level a parent concept must have to be considered for the is_a semantic closure expansion step.
  • For example, an annotation done with levelMin=1 & levelMax=3 will expand a direct annotations done with a concept up to the 3rd level parent in the is_a hierarchy for this concept. An annotation done with levelMin=0 & levelMax=0 is equivalent to disable the is_a transitive closure expansion step.
mappingTypes {null,mappingType1,...,mappingTypeN} default: empty (i.e. all mappingTypes) Specifies the list of mapping type to use during the mapping expansion step. The list of rmapping types that can be used is available at the /obs/mappingTypes URL. The current list is described in section Mapping types.
  • For example, from-mrrel,Human.
  • Note that the use of the key word "null" in the mappingTypes list disables the mapping expansion component. Note also that the mapping expansion is also limited by other parameters such as ontologiesToExpand and ontologiesToKeepInResult.
localConceptIDs {localConceptID1,...,localConceptIDN} default: empty (i.e. all concepts) Specifies the list of concept to use to query the Resource index (i.e., get the annotations done with this list). This parameter must be jointly specified with the mode parameter. If localConceptIDs contains only one element then the mode parameter can be ignored.The values are separated with comma (without spaces).
  • For example, NCI/C0025202,4513/Virtual_surface.
virtual {true, false} default: false Specifies the if the list of ontologies are all BioPortal virtual ontology IDs or UMLS ontologies.
mode {union, intersection} default: union Specifies the mode to use when querying the resource index with several concept (parameter localConceptIDs). The union mode returns the union of all the annotations (filtered eventually with other parameters) done with each specified localConceptID. The intersection mode returns the intersection.
localElementID default: all Specifies the identifier of the resource element for which annotations are requested. The localElementID is defined by the original resource e.g., PMID for PubMed, NCT for ClinicalTrials. The full list of the localElementID type is defined in Section Local element ID used.
  • For example, NCT00001589 or GDS2735.
resourceID default: all Specifies the resource to filter the annotations with. The resource_identifier used for this parameter identify a resource in the OBR index. They are defined in section Resource identifiers.The list of resourceID can be used is available at the /obs/resources URL.
  • For example, GEO,CT,AE.
elementDetails {true, false} default: false Specifies the if the returned resource elements to be detailed or not.
withContext {true, false} default: true Specifies whether the annotations context information to be available or not.If turn to false, the set of annotations returned will be simplified and will not detail the context information for an annotation. Only the score will be returned (which implies score=true)
from and number {real_number} default: 1/10 respectively Specifies an offset of annotations defined by from and number.
format {asText ,asTabDelimited, asXML ,asOWL} default: asXML Specifies the desired format of the response.


Web Service Response

Response Format

xml returns XML representation of the ObrResultBeanDetailled.
text returns plain text representation of the ObrResultBeanDetailled.
tabDelimited shorter version of "Text" format. returns not the full result content but the annotations only (no statistics, etc.). The format of the tab delimited file is: score \t conceptId \t preferredName \t synonyms (separated by ' /// ') \t semanticType (separated by ' /// ') \t contextName \t isDirect \t other context information (e.g., childConceptId, mappedConceptId, level, mappingType) (separated by ' /// ').
OWL returns OWL representation of the ObrResultBeanDetailled.

Note : if request parameter withContext is true, then returns representation of the ObrResultBeanDetailled and if request parameter withContext is false, then returns representation of the ObrResultBean.

Response Content: ObrResultBeanDetailled

Response ObrResultBeanDetailled contains all the contents of ObrResultBean. Those contents are described in section Response Content: ObrResultBean.

Following are remaining contents for ObrResultBeanDetailled :

directAnnotations ObrAnnotationBean is a representation of one annotation.
isaAnnotations ObrAnnotationBean is a representation of one annotation.
mappingAnnotations ObrAnnotationBean is a representation of one annotation.

Note : Response contents of the ObrAnnotationBean are described in section ObrResultBean annotations


Response Content: ObrResultBean

resultID
dictionary Dictionary contains the metadata (not the content) of the dictionary used for a result. dictionaryId, dictionaryName, and dictionaryDate identify the dictionary on the server side and give information about its content. Dictionary versioning is strongly linked to the evolution of the ontologies used. Each time ontologies change, the dictionary is updated. All the dictionary information may be useful for comparing results of the Annotator Restlet service on time.
statistics Statistics contains information on the number of annotations done for a given context. The contextName keyword identifies the type of context and nbAnnotation is the number of annotations of this type.
parameters Parameters summarizes all the parameters specified by the user when requesting the Annotator Restlet service. Those parameters are described in section Service parameters
ontologies To keep the model simple, we provide only the global ontology identifier, localOntologyId the name (ontologyName) and version (ontologyVersion). This information come from the original repositories (UMLS/BioPortal) and might help the user to select the right ontology to use. When an ontology is used in the annotation, a result has a set of OntologyUsed which specify 2 other properties: nbAnnotation, the number of annotation that have been made with concepts from this ontology. score, the sum of all the scores of the annotations done with concepts from this ontology (if parameter scored=true). Therefore, score represents the most accurate ontology to annotate the given text.
annotations ObrAnnotationBean/ObrAnnotationBeanDetailled is a representation of one annotation. If elementDetails parameter is true the service return response of type ObrAnnotationBean ,otherwise ObrAnnotationBeanDetailled. An annotation has a score which represents the accuracy of the annotation computed by the scoring algorithm (if the scored=true parameter was chosen, otherwise score=-1). An annotation is done with a concept in a context.

Response Content: ObrAnnotationBeanDetailled

Response ObrAnnotationBeanDetailled contains all the contents of ObrAnnotationBean. Those contents are described in section Response Content: ObrAnnotationBean.

Following are remaining contents for ObrAnnotationBeanDetailled :

element
  • localElementID - Global identifier for the resource element.
  • elementStructure - Represents Structure of an element for a given resource.

Response Content: Structure

resourceID resource identifier for Resource.
contexts list of context for resource.
itemKeys list of itemKeys for resource.
weights map contain weights (as double) for each context (as String).
ontoIDs map contain ontologyIDs for each context (as String).

Response Content: ObrAnnotationBean

localElementID Identifier for resource element.
score
concept
  • localConceptId - global identifier for the concept in its original repository.
  • localOntologyId - identifier for the ontology in which the concept is defined.
  • isTopLevel - specifies if the concept is a root concept in its ontology.
  • preferredName - label or preferred term for this concept (as assigned by the original repository).
  • synonyms - the set of possible terms that represent the concept but are not preferred.
  • semanticTypes - the set of the semantic types of the concept (assigned by UMLS + T000 and T999).
context Context specifies if it is a direct or expanded annotation and give precision about the origin of the annotation. contextName identifies the type of context. The context properties vary with the type of concept. There are 3 possible contexts identified by their contextName:
MGREP represents direct annotations done with the Mgrep concept recognizer. A Mgrep context has 3 properties:
  • termName - the expression (preferred name or synonyms) that was matched by Mgrep.
  • from and to - specify the character index in the given text for the matched expression.
ISA_CLOSURE represents expanded annotations done with the is_a transitive closure expansion component. A ISA_CLOSURE context has 2 properties:
  • childConceptId - the concept from which the annotation was derived.
  • level - the distance in the is_a hierarchy between the annotating concept and the concept from which the annotation was derived.
  • For example, if a direct annotation with NCI/C0025202 (melanoma) was done, the is_a transitive closure component may expand it to another annotation with NCI/C1302746 (Melanocytic Neoplasm) because the latter is a direct parent (i.e., level 1) concept of the former. The ISA_CLOSURE annotation generated will have the following properties {NCI/C0025202, 1}.
MAPPING represents expanded annotations done with the mapping expansion component. A MAPPING context has 2 properties:
  • mappedConceptId identifies the concept from which the annotation was derived.
  • mappingType specifies the type of mapping.
localElementID localConceptIDs mode withContext elementDetails counts offsetStart offsetMax Parameters summarizes all the parameters specified by the user when requesting the Resource Index Restlet service. Those parameters are described in section Service parameters


Other GET Services

Following section describes all other simplified GET services available in Resource_Index_API.

Annotation by Concept Service

Returns the set of annotations done with a given localConceptID.

  • Response Content : ObrResultBean/ObrResultBeanDetailled. If request parameter withContext is true, then returns representation of the ObrResultBeanDetailled and if request parameter withContext is false, then returns representation of the ObrResultBean.

Annotation for BioPortal virtual ontology Concept Service

Returns the set of all annotations done with a given localConceptID using BioPortal virtual ontology ID.

  • GET Request Format : /byconcept/virtual/{virtualOntologyID}/{conceptID}/{withContext}/{counts}/{from}/{number}
  • Response Content : ObrResultBean/ObrResultBeanDetailled.

Annotation By Concept And Resource Service

Returns the set of all annotations done with a given localConceptID for given resourceID.

  • GET Request Format : /byconcept/{ontologyID}/{conceptID}/{resourceID}/{withContext}/{counts}/{from}/{number}
  • Response Content : ObrResultBean/ObrResultBeanDetailled.

Annotation for BioPortal virtual ontology Concept And Resource Service

Returns the set of all annotations done with a given localConceptID using BioPortal virtual ontology ID and using particular resourceID.

  • GET Request Format : /byconcept/virtual/{virtualOntologyID}/{conceptID}/{resourceID}/{withContext}/{counts}/{from}/{number}
  • Response Content : ObrResultBean/ObrResultBeanDetailled.

Annotation By Resource Element Service

Returns the set of all annotations done with a given resource element localElementID for all the concepts.

  • GET Request Format : /byelement/{resourceID}/{localElementID}/{withContext}/{counts}/{from}/{number}
  • Response Content : ObrResultBean/ObrResultBeanDetailled.

Annotation Details By Resource Element Service

Returns the set of all annotations details with a given resource element localElementID for given conceptID

  • GET Request Format : /details/concept/{ontologyID}/{conceptID}/resource/{resourceID}/element/{localElementID}
  • Response Content : ObrAnnotationBean.

Annotation Details By Resource Element Service for BioPortal Virtual OntologyID

Returns the set of all annotations details with a given resource element localElementID for given conceptID of BioPortal virtual ontologyID

  • GET Request Format : /details/virtual/concept/{virtualOntologyID}/{conceptID}/resource/{resourceID}/element/{localElementID}
  • Response Content : ObrAnnotationBean.

Resources Service

Returns the set of all resources available in resource index and information related to it.

  • Response Content : Resource is a representation of one resource

Response Content: Resource

resourceName Name of the particular resource.
resourceID Identifier of the resource.
mainContext Main context string for the resource.
resourceURL Website URL for the resource
resourceElementURL Base URL for getting elements for resource.
resourceDescription Description of the resource.
resourceLogo URL of logo image for the resource.
resourceStructure Represents Structure of an element for the resource.

Response Content: Structure

resourceID resource identifier for Resource.
contexts list of context for resource.
itemKeys list of itemKeys for resource.
weights map contain weights (as double) for each context (as String).
ontoIDs map contain ontologyIDs for each context (as String).

Resource Service

Returns the resource in resource index for given resourceID and information related to it.

  • GET Request Format : /resources/{resourceID}
  • Response Content : Resource.

Resource Element Service

Service returns elementURL for given localElementID and redirect it to get resource element on the web.

  • GET Request Format : /resources/{resourceID}
  • Response Content : Web page containing details of the element.
Retrieved from "https://www.bioontology.org//mediawiki/index.php?title=Resource_Index_REST_Web_Service_User_Guide&oldid=9317"