Difference between revisions of "BioPortal REST services"

From NCBO Wiki
Jump to navigation Jump to search
Line 345: Line 345:
 
* '''Description''': The same as the previous service, but takes an ontology id and returns parents from the latest version of that ontology.
 
* '''Description''': The same as the previous service, but takes an ontology id and returns parents from the latest version of that ontology.
  
−
= Usage Logging =
 
−
* '''Signature''': ./usage?{args}
 
−
* '''Example''': http://rest.bioontology.org/bioportal/usage?requesturl=ontologies&resourceparameters=13578&email=example@example.org
 
−
* '''Required arguments:'''
 
−
** none specifically, but at least one optional argument is required
 
−
* '''Optional arguments:'''
 
−
** requesturl=<string contained in request url> – limit results to a given string contained in REST service request url
 
−
** resourceparameters=<string contained in resource parameters> – limit results to a given string contained in resource parameters. For example, in the URL http://rest.bioontology.org/bioportal/search/melanoma, the word "melanoma" is considered a "resource parameter".
 
−
** startdateaccessed=<date in format mm/dd/yyyy> – limit results to the given starting date (default: no starting date)
 
−
** startdateaccessed=<date in format mm/dd/yyyy> – limit results to the given ending date (default: today's date)
 
−
* '''Description''': returns BioPortal REST services usage data as XML.
 
−
* '''Sample Output:'''
 
−
<pre>
 
−
<?xml version="1.0" encoding="UTF-8" ?>
 
−
<success>
 
−
<accessedResource>/bioportal/usage</accessedResource>
 
−
<accessDate>2009-07-27 14:21:19.728 PDT</accessDate>
 
−
<data>
 
−
<list>
 
−
<usageLoggingBean>
 
−
<requestUrl>
 
−
/search/Certain infectious and parasitic diseases/
 
−
</requestUrl>
 
−
<httpMethod>GET</httpMethod>
 
−
<resourceParameters>
 
−
query=Certain%20infectious%20and%20parasitic%20diseases
 
−
</resourceParameters>
 
−
<requestParameters>
 
−
pagenum=1&ontologyids=1265&pagesize=20
 
−
</requestParameters>
 
−
<hitCount>1</hitCount>
 
−
<dateAccessed class="sql-timestamp">
 
−
2009-07-27 00:00:00.0
 
−
</dateAccessed>
 
−
</usageLoggingBean>
 
−
<usageLoggingBean>
 
−
<requestUrl>/search/Hypertension/</requestUrl>
 
−
<httpMethod>GET</httpMethod>
 
−
<resourceParameters>
 
−
query=Hypertension
 
−
</resourceParameters>
 
−
<requestParameters>
 
−
pagenum=1&ontologyids=1265&pagesize=20
 
−
</requestParameters>
 
−
<hitCount>2</hitCount>
 
−
<dateAccessed class="sql-timestamp">
 
−
2009-07-27 00:00:00.0
 
−
</dateAccessed>
 
−
</usageLoggingBean>
 
−
<usageLoggingBean>
 
−
<requestUrl>/search/Melanoma/</requestUrl>
 
−
<httpMethod>GET</httpMethod>
 
−
<resourceParameters>query=Melanoma</resourceParameters>
 
−
<requestParameters>
 
−
pagenum=1&ontologyids=1265&pagesize=20
 
−
</requestParameters>
 
−
<hitCount>3</hitCount>
 
−
<dateAccessed class="sql-timestamp">
 
−
2009-07-27 00:00:00.0
 
−
</dateAccessed>
 
−
</usageLoggingBean>
 
−
</list>
 
−
</data>
 
−
</success>
 
−
</pre>
 
  
 
= Mapping Service =
 
= Mapping Service =
Line 498: Line 433:
  
 
</pre>
 
</pre>
 +
 +
 +
= Annotation Service =
 +
 +
= Usage Logging =
 +
* '''Signature''': ./usage?{args}
 +
* '''Example''': http://rest.bioontology.org/bioportal/usage?requesturl=ontologies&resourceparameters=13578&email=example@example.org
 +
* '''Required arguments:'''
 +
** none specifically, but at least one optional argument is required
 +
* '''Optional arguments:'''
 +
** requesturl=<string contained in request url> – limit results to a given string contained in REST service request url
 +
** resourceparameters=<string contained in resource parameters> – limit results to a given string contained in resource parameters. For example, in the URL http://rest.bioontology.org/bioportal/search/melanoma, the word "melanoma" is considered a "resource parameter".
 +
** startdateaccessed=<date in format mm/dd/yyyy> – limit results to the given starting date (default: no starting date)
 +
** startdateaccessed=<date in format mm/dd/yyyy> – limit results to the given ending date (default: today's date)
 +
* '''Description''': returns BioPortal REST services usage data as XML.
 +
* '''Sample Output:'''
 +
<pre>
 +
<?xml version="1.0" encoding="UTF-8" ?>
 +
<success>
 +
<accessedResource>/bioportal/usage</accessedResource>
 +
<accessDate>2009-07-27 14:21:19.728 PDT</accessDate>
 +
<data>
 +
<list>
 +
<usageLoggingBean>
 +
<requestUrl>
 +
/search/Certain infectious and parasitic diseases/
 +
</requestUrl>
 +
<httpMethod>GET</httpMethod>
 +
<resourceParameters>
 +
query=Certain%20infectious%20and%20parasitic%20diseases
 +
</resourceParameters>
 +
<requestParameters>
 +
pagenum=1&ontologyids=1265&pagesize=20
 +
</requestParameters>
 +
<hitCount>1</hitCount>
 +
<dateAccessed class="sql-timestamp">
 +
2009-07-27 00:00:00.0
 +
</dateAccessed>
 +
</usageLoggingBean>
 +
<usageLoggingBean>
 +
<requestUrl>/search/Hypertension/</requestUrl>
 +
<httpMethod>GET</httpMethod>
 +
<resourceParameters>
 +
query=Hypertension
 +
</resourceParameters>
 +
<requestParameters>
 +
pagenum=1&ontologyids=1265&pagesize=20
 +
</requestParameters>
 +
<hitCount>2</hitCount>
 +
<dateAccessed class="sql-timestamp">
 +
2009-07-27 00:00:00.0
 +
</dateAccessed>
 +
</usageLoggingBean>
 +
<usageLoggingBean>
 +
<requestUrl>/search/Melanoma/</requestUrl>
 +
<httpMethod>GET</httpMethod>
 +
<resourceParameters>query=Melanoma</resourceParameters>
 +
<requestParameters>
 +
pagenum=1&ontologyids=1265&pagesize=20
 +
</requestParameters>
 +
<hitCount>3</hitCount>
 +
<dateAccessed class="sql-timestamp">
 +
2009-07-27 00:00:00.0
 +
</dateAccessed>
 +
</usageLoggingBean>
 +
</list>
 +
</data>
 +
</success>
 +
</pre>
 +
 +
 +
= Overview - Using NCBO Technology in Your Project =
 +
General information on using [http://www.bioontology.org/wiki/index.php/Using_NCBO_Technology_In_Your_Project NCBO Technology in your Project].

Revision as of 11:18, 6 August 2009

This page documents BioPortal Web Service signatures. The list below contains commonly accessed BioPortal Web services and is not intended to be an exhaustive list. If a feature you are interested in is not in the list below, please contact BioPortal Support to request the service or ask for more details on the full list of services.

The prefix for all service URLs in the table below is http://rest.bioontology.org/bioportal/

  • Note: All NCBO REST web service calls MUST append a user identification query parameter with the pattern of "email=UserEmail" (note some clients may need to use URL encoding). For example, email=example@example.org or email=example%40example.org as an encoded email. Please start adding the user identification URL parameter to all your web service invocations. Later in 2009, we may start challenging REST service calls that do not have this parameter.
  • Note: Signatures for BioPortal services have changed in BioPortal 2.0.4 release on January 13th, 2009. This page has the new service URLs. If you have any questions, please contact BioPortal Support.


Services to access ontologies and ontology versions

List all the latest version of ontologies

Get a specific ontology based on a version id

Download an ontology file

Get all versions of an ontology form a virtual ontology id

Get latest version of an ontology id

List all ontology categories id

Concept services

Get concept

Get all root concepts for an ontology id

Get concept for latest ontology version id

Search services

Search BioPortal

  • Signature: ./search/{query}[?{optional args}]&email={email_address}
  • Example: http://rest.bioontology.org/bioportal/search/Gene?email=example@example.org
  • You can use multiple query terms, separated by a space, for example: http://rest.bioontology.org/bioportal/search/lung disease?email=example@example.org
  • Optional arguments:
    • ontologyids=<ontologyid>,<ontologyid>… - limits the search to specific ontologies (default: all ontologies)
    • isexactmatch=[1/0] – match the entire concept name (default: 0)
    • includeproperties=[1/0] – include attributes in the search (default: 0)
    • pagesize=<pagesize> - the number of results to display in a single request (default: all)
    • pagenum=<pagenum> - the page number to display (pages are calculated using <total results>/<pagesize>) (default: 1)
    • maxnumhits=<maxnumhits> - the maximum number of top matching results to return (default: 1000)
  • Description:

The search attempts to match both partial and exact queries, giving more weight to exact matches. In single-word searches, the wildcard character (*) is automatically appended to the end of the word. For example, searching for "lun" would return all concepts whose name contains a word that begins with "lun" (i.e. "Lung", "Murine Lunate Bone", "Base of the Lung", etc).

In phrase searches (multiple words), the wildcard character is appended to the last word. For example, searching for "cutaneous mela" would return all concepts whose name contains the word "cutaneous", followed by any word that begins with "mela" (i.e. "Cutaneous Melanoma", "Metastatic Non-Cutaneous Melanoma", "Cutaneous Melanoma Clinical TNM Finding", etc). 

<?xml version="1.0" encoding="UTF-8" ?>
<success>
	<accessedResource>
		/bioportal/search/cutaneous%20mela
	</accessedResource>
	<accessDate>2009-05-07 16:17:46.182 PDT</accessDate>
	<data>
		<page>
			<pageNum>1</pageNum>
			<numPages>1</numPages>
			<pageSize>3</pageSize>
			<numResultsPage>3</numResultsPage>
			<numResultsTotal>3</numResultsTotal>
			<contents
				class="org.ncbo.stanford.bean.search.SearchResultListBean">
				<searchResultList>
					<searchBean>
						<ontologyVersionId>39715</ontologyVersionId>
						<ontologyId>1136</ontologyId>
						<ontologyDisplayLabel>
							Experimental Factor Ontology
						</ontologyDisplayLabel>
						<recordType>
							RECORD_TYPE_PREFERRED_NAME
						</recordType>
						<conceptId>
							http://www.ebi.ac.uk/efo/EFO_0000389
						</conceptId>
						<conceptIdShort>EFO_0000389</conceptIdShort>
						<preferredName>
							cutaneous melanoma
						</preferredName>
						<contents>cutaneous melanoma</contents>
					</searchBean>
					<searchBean>
						<ontologyVersionId>39478</ontologyVersionId>
						<ontologyId>1032</ontologyId>
						<ontologyDisplayLabel>
							NCI Thesaurus
						</ontologyDisplayLabel>
						<recordType>
							RECORD_TYPE_PREFERRED_NAME
						</recordType>
						<conceptId>
							http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#Cutaneous_Melanoma
						</conceptId>
						<conceptIdShort>
							Cutaneous_Melanoma
						</conceptIdShort>
						<preferredName>
							Cutaneous Melanoma
						</preferredName>
						<contents>Cutaneous Melanoma</contents>
					</searchBean>
					<searchBean>
						<ontologyVersionId>39833</ontologyVersionId>
						<ontologyId>1009</ontologyId>
						<ontologyDisplayLabel>
							Human disease
						</ontologyDisplayLabel>
						<recordType>
							RECORD_TYPE_PREFERRED_NAME
						</recordType>
						<conceptId>DOID:2418</conceptId>
						<conceptIdShort>DOID:2418</conceptIdShort>
						<preferredName>
							Cutaneous Melanocytic Neoplasm
						</preferredName>
						<contents>
							Cutaneous Melanocytic Neoplasm
						</contents>
					</searchBean>
				</searchResultList>
				<ontologyHitList>
					<ontologyHitBean>
						<ontologyVersionId>39715</ontologyVersionId>
						<ontologyId>1136</ontologyId>
						<ontologyDisplayLabel>
							Experimental Factor Ontology
						</ontologyDisplayLabel>
						<numHits>1</numHits>
					</ontologyHitBean>
					<ontologyHitBean>
						<ontologyVersionId>39833</ontologyVersionId>
						<ontologyId>1009</ontologyId>
						<ontologyDisplayLabel>
							Human disease
						</ontologyDisplayLabel>
						<numHits>1</numHits>
					</ontologyHitBean>
					<ontologyHitBean>
						<ontologyVersionId>39478</ontologyVersionId>
						<ontologyId>1032</ontologyId>
						<ontologyDisplayLabel>
							NCI Thesaurus
						</ontologyDisplayLabel>
						<numHits>1</numHits>
					</ontologyHitBean>
				</ontologyHitList>
			</contents>
		</page>
	</data>
</success>

Hierarchy Services

Get parents/children of a given concept in a specific ontology version

<?xml version="1.0" encoding="UTF-8" ?>
<success>
	<accessedResource>
		/bioportal/virtual/parents/MSH/C0025202
	</accessedResource>
	<accessDate>2009-04-21 10:55:33.494 PDT</accessDate>
	<data>
		<list>
			<classBean>
				<ontologyVersionId>MSH</ontologyVersionId>
				<id>C0206769</id>
				<relations>
					<entry>
						<string>Level</string>
						<int>1</int>
					</entry>
				</relations>
			</classBean>
			<classBean>
				<ontologyVersionId>MSH</ontologyVersionId>
				<id>C0206754</id>
				<relations>
					<entry>
						<string>Level</string>
						<int>1</int>
					</entry>
				</relations>
			</classBean>
		</list>
	</data>
</success>

Get parents/children of a given concept in the latest version of a given ontology

Get paths to roots/leaves from a concept in a specific ontology version

<?xml version="1.0" encoding="UTF-8" ?>
<success>
	<accessedResource>
		/bioportal/concepts/rootpath/13578/Melanoma
	</accessedResource>
	<accessDate>2009-04-21 11:06:23.439 PDT</accessDate>
	<data>
		<list>
			<classBean>
				<ontologyVersionId>13578</ontologyVersionId>
				<id>Melanoma</id>
				<relations>
					<entry>
						<string>Path</string>
						<string>
							Getings_and_Disorders_Kind.Diseases_Disorders_and_Getings.Diseases_and_Disorders.Neoplasm.Neoplasm_by_Morphology.Melanocytic_Neoplasm
						</string>
					</entry>
				</relations>
			</classBean>
			<classBean>
				<ontologyVersionId>13578</ontologyVersionId>
				<id>Melanoma</id>
				<relations>
					<entry>
						<string>Path</string>
						<string>
							Getings_and_Disorders_Kind.Diseases_Disorders_and_Getings.Diseases_and_Disorders.Neoplasm.Neoplasm_by_Special_Category.Common_Neoplasm
						</string>
					</entry>
				</relations>
			</classBean>
		</list>
	</data>
</success>

Get paths to root/leaves from a concept in the latest version of a given ontology

Get siblings of a given concept in a specific ontology version

  • Signature: ./concepts/siblings/{ontlogyVersionId}/{conceptId}?level=<level>&email={email_address}&[&{optional args}]
  • Example: http://rest.bioontology.org/bioportal/concepts/siblings/13578/Melanoma?level=1&email=example@example.org
  • Required arguments:
    • level=<integer> - limits results to a given level in the hierarchy
  • Optional arguments:
    • offset=<integer> – results offset (used for pagination)
  • Description: returns the set of sibling concepts at the given level (i.e., siblings that have the same direct (level=1), grand-parents (level=2), etc.) for a given concept.
  • Note: These services accepts UMLS Abbreviated source name (SAB) for ontlogyVersionId and UMLS Unique identifier for concept (CUI) fro conceptId.
  • Sample Output:
<?xml version="1.0" encoding="UTF-8" ?>
<success>
	<accessedResource>
		/bioportal/concepts/siblings/13578/Melanoma
	</accessedResource>
	<accessDate>2009-04-21 11:15:13.427 PDT</accessDate>
	<data>
		<list>
			<classBean>
				<ontologyVersionId>13578</ontologyVersionId>
				<id>Common_Germ_Cell_Neoplasm</id>
				<relations>
					<entry>
						<string>Level</string>
						<int>1</int>
					</entry>
				</relations>
			</classBean>
			<classBean>
				<ontologyVersionId>13578</ontologyVersionId>
				<id>Common_Hematopoietic_Neoplasm</id>
				<relations>
					<entry>
						<string>Level</string>
						<int>1</int>
					</entry>
				</relations>
			</classBean>
		</list>
	</data>
</success>

Get siblings of a given concept in the latest version of a given ontology

  • Signature: ./virtual/siblings/{ontlogyId}/{conceptId}?level=<level>&email={email_address}&[&{optional args}]
  • Example: http://rest.bioontology.org/bioportal/virtual/siblings/1009/DOID:1909?level=1&email=example@example.org
  • Required arguments:
    • level=<integer> - limits results to a given level in the hierarchy
  • Optional arguments:
    • offset=<integer> – results offset (used for pagination)
  • Description: The same as the previous service, but takes an ontology id and returns parents from the latest version of that ontology.


Mapping Service

  • Signature: ./mappings/service/{ontology_id}/{concept_id}
  • Example: http://bioportal.bioontology.org/mappings/service/1083/
  • Required arguments:
    • ontology_id
  • Optional arguments:
    • concept_id=if concept_id is included, the service will return all mappings to and from the given concept
  • Description: returns BioPortal Mappings as XML.
  • Sample Output:
<hash>
  <mapping-from type="array">
    <mapping-from>
      <comment nil="true"></comment>
      <map-type>Human</map-type>
      <created-at>2008-05-09 08:25:23</created-at>
      <updated-at>2008-08-05 17:26:06</updated-at>

      <source-name>Carbon</source-name>
      <source-ont-name>NanoParticle Ontology (NPO)</source-ont-name>
      <destination-id>CHEBI:27594</destination-id>
      <id>98216</id>
      <user-id>38139</user-id>
      <relationship-type nil="true"></relationship-type>

      <destination-ont-name>Chemical entities of biological interest</destination-ont-name>
      <destination-name>Carbon</destination-name>
      <map-source nil="true"></map-source>
      <destination-ont>1007</destination-ont>
      <source-id>Carbon</source-id>
      <destination-version-id>38377</destination-version-id>

      <source-version-id>29531</source-version-id>
      <source-ont>1083</source-ont>
    </mapping-from>   
    <mapping-from>
      <comment nil="true"></comment>
      <map-type>Human</map-type>
      <created-at>2008-05-09 08:27:05</created-at>

      <updated-at>2008-08-05 17:26:06</updated-at>
      <source-name>Gold</source-name>
      <source-ont-name>NanoParticle Ontology (NPO)</source-ont-name>
      <destination-id>CHEBI:29287</destination-id>
      <id>98218</id>
      <user-id>38139</user-id>

      <relationship-type nil="true"></relationship-type>
      <destination-ont-name>Chemical entities of biological interest</destination-ont-name>
      <destination-name>Gold</destination-name>
      <map-source nil="true"></map-source>
      <destination-ont>1007</destination-ont>
      <source-id>Gold</source-id>
      <destination-version-id>38377</destination-version-id>

      <source-version-id>29531</source-version-id>
      <source-ont>1083</source-ont>
    </mapping-from>
  </mapping-from>
  <mapping-to type="array">
    <mapping-to>
      <comment nil="true"></comment>
      <map-type>Human</map-type>

      <created-at>2008-05-09 08:35:27</created-at>
      <updated-at>2008-08-05 17:26:06</updated-at>
      <source-name>Carbohydrate</source-name>
      <source-ont-name>NanoParticle Ontology (NPO)</source-ont-name>
      <destination-id>Carbohydrate</destination-id>
      <id>98219</id>

      <user-id>38139</user-id>
      <relationship-type nil="true"></relationship-type>
      <destination-ont-name>NanoParticle Ontology (NPO)</destination-ont-name>
      <destination-name>Carbohydrate</destination-name>
      <map-source nil="true"></map-source>
      <destination-ont>1083</destination-ont>
      <source-id>Carbohydrate</source-id>

      <destination-version-id>29531</destination-version-id>
      <source-version-id>29531</source-version-id>
      <source-ont>1083</source-ont>
    </mapping-to>
  </mapping-to>
</hash>


Annotation Service

Usage Logging

  • Signature: ./usage?{args}
  • Example: http://rest.bioontology.org/bioportal/usage?requesturl=ontologies&resourceparameters=13578&email=example@example.org
  • Required arguments:
    • none specifically, but at least one optional argument is required
  • Optional arguments:
    • requesturl=<string contained in request url> – limit results to a given string contained in REST service request url
    • resourceparameters=<string contained in resource parameters> – limit results to a given string contained in resource parameters. For example, in the URL http://rest.bioontology.org/bioportal/search/melanoma, the word "melanoma" is considered a "resource parameter".
    • startdateaccessed=<date in format mm/dd/yyyy> – limit results to the given starting date (default: no starting date)
    • startdateaccessed=<date in format mm/dd/yyyy> – limit results to the given ending date (default: today's date)
  • Description: returns BioPortal REST services usage data as XML.
  • Sample Output:
<?xml version="1.0" encoding="UTF-8" ?>
<success>
	<accessedResource>/bioportal/usage</accessedResource>
	<accessDate>2009-07-27 14:21:19.728 PDT</accessDate>
	<data>
		<list>
			<usageLoggingBean>
				<requestUrl>
					/search/Certain infectious and parasitic diseases/
				</requestUrl>
				<httpMethod>GET</httpMethod>
				<resourceParameters>
					query=Certain%20infectious%20and%20parasitic%20diseases
				</resourceParameters>
				<requestParameters>
					pagenum=1&ontologyids=1265&pagesize=20
				</requestParameters>
				<hitCount>1</hitCount>
				<dateAccessed class="sql-timestamp">
					2009-07-27 00:00:00.0
				</dateAccessed>
			</usageLoggingBean>
			<usageLoggingBean>
				<requestUrl>/search/Hypertension/</requestUrl>
				<httpMethod>GET</httpMethod>
				<resourceParameters>
					query=Hypertension
				</resourceParameters>
				<requestParameters>
					pagenum=1&ontologyids=1265&pagesize=20
				</requestParameters>
				<hitCount>2</hitCount>
				<dateAccessed class="sql-timestamp">
					2009-07-27 00:00:00.0
				</dateAccessed>
			</usageLoggingBean>
			<usageLoggingBean>
				<requestUrl>/search/Melanoma/</requestUrl>
				<httpMethod>GET</httpMethod>
				<resourceParameters>query=Melanoma</resourceParameters>
				<requestParameters>
					pagenum=1&ontologyids=1265&pagesize=20
				</requestParameters>
				<hitCount>3</hitCount>
				<dateAccessed class="sql-timestamp">
					2009-07-27 00:00:00.0
				</dateAccessed>
			</usageLoggingBean>
		</list>
	</data>
</success>


Overview - Using NCBO Technology in Your Project

General information on using NCBO Technology in your Project.

Retrieved from "https://www.bioontology.org//mediawiki/index.php?title=BioPortal_REST_services&oldid=9096"