Difference between revisions of "BioPortal REST services"

From NCBO Wiki
Jump to navigation Jump to search
Line 65: Line 65:
 
Those services accepts 3 kinds of ontologyId:
 
Those services accepts 3 kinds of ontologyId:
 
* BioPortal ontology version id
 
* BioPortal ontology version id
* BioPortal ontology virtual id. In that case the latest version of the ontology is used.
+
* BioPortal ontology virtual id. In that case the latest version of the ontology is used (If the latest version of the ontology is not in our index for hierarchy services, returns an error).
 
* UMLS Abbreviated source name (SAB). In that case the conceptId must be a UMLS Unique identifier for concept (CUI) defined in that SAB.
 
* UMLS Abbreviated source name (SAB). In that case the conceptId must be a UMLS Unique identifier for concept (CUI) defined in that SAB.
  
Line 76: Line 76:
 
** limit=<integer> – limits the number of results
 
** limit=<integer> – limits the number of results
 
** '''Example''': http://rest.bioontology.org/bioportal/concepts/parents/13578/Melanoma?level=1&offset=1&limit=10
 
** '''Example''': http://rest.bioontology.org/bioportal/concepts/parents/13578/Melanoma?level=1&offset=1&limit=10
* '''Description''': returns all parents of the concept, with the level indicating how far away the parent is from the concept. For instance, direct parents have level 1; their direct parents have level 2, etc. If no level is specified, the service returns all the levels up to the root. If the level is specified, the service returns only the parents at that level.
+
* '''Description''': return all parents (resp. children) of the concept, with the level indicating how far away the parent (child) is from the concept. For instance, direct parents have level 1; their direct parents have level 2, etc. If no level is specified, the services return all the parents (resp. children) up to the ontology roots (resp. down to the ontology leaves). If the level is specified, the service returns only the parents (resp. children) at that level.
 
* '''Sample Output:'''  
 
* '''Sample Output:'''  
 
<pre>
 
<pre>
Line 112: Line 112:
 
</pre>
 
</pre>
  
==  Get parents of a given concept in the latest version of a given ontology ==
 
* '''Signature''': ./virtual/parents/{ontlogyId}/{conceptId}[?{optional args}]
 
* '''Example''': http://rest.bioontology.org/bioportal/virtual/parents/1032/Melanoma
 
* '''Optional arguments:'''
 
** level=<integer> - limits results to a given level in the hierarchy
 
** offset=<integer> – results offset (used for pagination)
 
** limit=<integer> – limits the number of results
 
** '''Example''': http://rest.bioontology.org/bioportal/virtual/parents/1032/Melanoma?level=1&offset=1&limit=10
 
* '''Description''': The same as the service to [[#Get parents of a given concept in a specific ontology version|get parents for a particular version]], but takes an ontology id and returns parents from the latest version of that ontology. If the latest version of the ontology is not in our index for hierarchy services, returns an error.
 
* '''Sample Output:'''
 
<pre>
 
<?xml version="1.0" encoding="UTF-8" ?>
 
<success>
 
<accessedResource>
 
/bioportal/concepts/parents/13578/Melanoma
 
</accessedResource>
 
<accessDate>2009-04-21 10:28:43.964 PDT</accessDate>
 
<data>
 
<list>
 
<classBean>
 
<ontologyVersionId>13578</ontologyVersionId>
 
<id>Common_Neoplasm</id>
 
<relations>
 
<entry>
 
<string>Level</string>
 
<int>1</int>
 
</entry>
 
</relations>
 
</classBean>
 
<classBean>
 
<ontologyVersionId>13578</ontologyVersionId>
 
<id>Diseases_and_Disorders</id>
 
<relations>
 
<entry>
 
<string>Level</string>
 
<int>4</int>
 
</entry>
 
</relations>
 
</classBean>
 
</list>
 
</data>
 
</success>
 
</pre>
 
 
==  Get children of a given concept in a specific ontology version ==
 
* '''Signature''': ./concepts/children/{ontlogyVersionId}/{conceptId}[?{optional args}]
 
* '''Example''': http://rest.bioontology.org/bioportal/concepts/children/13578/Melanoma
 
* '''Optional arguments:'''
 
** level=<integer> - limits results to a given level in the hierarchy
 
** offset=<integer> – results offset (used for pagination)
 
* '''Description''': returns all children of the concept, with the level indicating how far away the child node is from the concept. For instance, direct children have level 1; their direct children have level 2, etc. If no level is specified, the service returns all the levels up to the leaves. If the level is specified, the service returns only the children at that level.
 
* '''Sample Output:'''
 
<pre>
 
<?xml version="1.0" encoding="UTF-8" ?>
 
<success>
 
<accessedResource>
 
/bioportal/concepts/children/13578/Melanoma
 
</accessedResource>
 
<accessDate>2009-04-21 11:02:03.238 PDT</accessDate>
 
<data>
 
<list>
 
<classBean>
 
<ontologyVersionId>13578</ontologyVersionId>
 
<id>Non-Cutaneous_Melanoma</id>
 
<relations>
 
<entry>
 
<string>Level</string>
 
<int>1</int>
 
</entry>
 
</relations>
 
</classBean>
 
<classBean>
 
<ontologyVersionId>13578</ontologyVersionId>
 
<id>Recurrent_Melanoma</id>
 
<relations>
 
<entry>
 
<string>Level</string>
 
<int>1</int>
 
</entry>
 
</relations>
 
</classBean>
 
</list>
 
</data>
 
</success>
 
</pre>
 
 
==  Get children of a given concept in the latest version of a given ontology ==
 
* '''Signature''': ./virtual/children/{ontlogyId}/{conceptId}[?{optional args}]
 
* '''Example''': http://rest.bioontology.org/bioportal/virtual/children/1032/Melanoma
 
* '''Optional arguments:'''
 
** level=<integer> - limits results to a given level in the hierarchy
 
** offset=<integer> – results offset (used for pagination)
 
* '''Description''': The same as the service to [[#Get children of a given concept in a specific ontology version|get children for a particular version]], but takes an ontology id and returns children from the latest version of that ontology. If the latest version of the ontology is not in our index for hierarchy services, returns an error.
 
* '''Sample Output:'''
 
<pre>
 
<?xml version="1.0" encoding="UTF-8" ?>
 
<success>
 
<accessedResource>
 
/bioportal/virtual/children/MSH/C0025202
 
</accessedResource>
 
<accessDate>2009-04-21 11:04:26.733 PDT</accessDate>
 
<data>
 
<list>
 
<classBean>
 
<ontologyVersionId>MSH</ontologyVersionId>
 
<id>C0149722</id>
 
<relations>
 
<entry>
 
<string>Level</string>
 
<int>1</int>
 
</entry>
 
</relations>
 
</classBean>
 
<classBean>
 
<ontologyVersionId>MSH</ontologyVersionId>
 
<id>C0206735</id>
 
<relations>
 
<entry>
 
<string>Level</string>
 
<int>1</int>
 
</entry>
 
</relations>
 
</classBean>
 
</list>
 
</data>
 
</success>
 
</pre>
 
  
 
==  Get paths to root from a concept in a specific ontology version ==
 
==  Get paths to root from a concept in a specific ontology version ==

Revision as of 13:31, 23 April 2009

This page documents the signatures for NCBO (and, more specifically, BioPortal) REST services. This list may not be exhaustive.

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.

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

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 id

Get all root concepts for an ontology id

Get concept for latest ontology version id

Search services

Search BioPortal

Hierarchy Services

Those services accepts 3 kinds of ontologyId:

  • BioPortal ontology version id
  • BioPortal ontology virtual id. In that case the latest version of the ontology is used (If the latest version of the ontology is not in our index for hierarchy services, returns an error).
  • UMLS Abbreviated source name (SAB). In that case the conceptId must be a UMLS Unique identifier for concept (CUI) defined in that SAB.

Get parents|children of a given concept

  • Signature: ./concepts/[parents|children]/{ontlogyId}/{conceptId}[?{optional args}]
  • Example: http://rest.bioontology.org/bioportal/concepts/parents/13578/Melanoma
  • Optional arguments:
  • Description: return all parents (resp. children) of the concept, with the level indicating how far away the parent (child) is from the concept. For instance, direct parents have level 1; their direct parents have level 2, etc. If no level is specified, the services return all the parents (resp. children) up to the ontology roots (resp. down to the ontology leaves). If the level is specified, the service returns only the parents (resp. children) at that level.
  • Sample Output:
<?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 paths to root 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 from a concept in the latest version of a given ontology

<?xml version="1.0" encoding="UTF-8" ?>
<success>
	<accessedResource>
		/bioportal/virtual/rootpath/MSH/C0025202
	</accessedResource>
	<accessDate>2009-04-21 11:08:05.811 PDT</accessDate>
	<data>
		<list>
			<classBean>
				<ontologyVersionId>MSH</ontologyVersionId>
				<id>C0025202</id>
				<relations>
					<entry>
						<string>Path</string>
						<string>
							C1256739.C1256741.C0012674.C0027651.C0027652.C0206769
						</string>
					</entry>
				</relations>
			</classBean>
			<classBean>
				<ontologyVersionId>MSH</ontologyVersionId>
				<id>C0025202</id>
				<relations>
					<entry>
						<string>Path</string>
						<string>
							C1256739.C1256741.C0012674.C0027651.C0027652.C0027658.C0206093.C0206754
						</string>
					</entry>
				</relations>
			</classBean>
		</list>
	</data>
</success>

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

<?xml version="1.0" encoding="UTF-8" ?>
<success>
	<accessedResource>
		/bioportal/concepts/leafpath/13578/Melanoma
	</accessedResource>
	<accessDate>2009-04-21 11:10:04.386 PDT</accessDate>
	<data>
		<list>
			<classBean>
				<ontologyVersionId>13578</ontologyVersionId>
				<id>Melanoma</id>
				<relations>
					<entry>
						<string>Path</string>
						<string>
							Regressing_Non-Cutaneous_Melanoma.Regressing_Melanoma
						</string>
					</entry>
				</relations>
			</classBean>
			<classBean>
				<ontologyVersionId>13578</ontologyVersionId>
				<id>Melanoma</id>
				<relations>
					<entry>
						<string>Path</string>
						<string>
							Regressing_Melanoma_of_the_Skin.Regressing_Melanoma
						</string>
					</entry>
				</relations>
			</classBean>
		</list>
	</data>
</success>

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

<?xml version="1.0" encoding="UTF-8" ?>
<success>
	<accessedResource>
		/bioportal/virtual/leafpath/MSH/C0025202
	</accessedResource>
	<accessDate>2009-04-21 11:11:56.348 PDT</accessDate>
	<data>
		<list>
			<classBean>
				<ontologyVersionId>MSH</ontologyVersionId>
				<id>C0025202</id>
				<relations>
					<entry>
						<string>Path</string>
						<string>C0025205</string>
					</entry>
				</relations>
			</classBean>
			<classBean>
				<ontologyVersionId>MSH</ontologyVersionId>
				<id>C0025202</id>
				<relations>
					<entry>
						<string>Path</string>
						<string>C0206735</string>
					</entry>
				</relations>
			</classBean>
		</list>
	</data>
</success>

Get siblings of a given concept in a specific ontology version

<?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

<?xml version="1.0" encoding="UTF-8" ?>
<success>
	<accessedResource>
		/bioportal/virtual/siblings/MSH/C0206093
	</accessedResource>
	<accessDate>2009-04-21 11:30:12.183 PDT</accessDate>
	<data>
		<list>
			<classBean>
				<ontologyVersionId>MSH</ontologyVersionId>
				<id>C0206720</id>
				<relations>
					<entry>
						<string>Level</string>
						<int>2</int>
					</entry>
				</relations>
			</classBean>
			<classBean>
				<ontologyVersionId>MSH</ontologyVersionId>
				<id>C0206727</id>
				<relations>
					<entry>
						<string>Level</string>
						<int>2</int>
					</entry>
				</relations>
			</classBean>
		</list>
	</data>
</success>