API Documentation

General Usage

This API is comprised of a set of resources (Ontologies, Classes, etc) and related endpoints (Search, Annotator, Recommender)
that are connected together via links, much like webpages.
We recommend that you try browsing the API using a web browser (Chrome and Firefox work very well while IE does not)
before you start writing code.
For more information, please see the documentation on
Media Types and Hypermedia Links
or view our
sample code
, available in Java, Python, Ruby and other languages (please email
support@bioontology.org
if you would like examples in another language).

Common Parameters

Parameter

Possible Values

Description

apikey

{your api key}

An API Key is required to access any API call. It can be provided in three ways:

When using a web browser to explore the API, if you provide your API Key once using method 1, it will be stored in a cookie for subsequent requests. You can override this by providing a different API Key in a new call.

include

all
{comma-separated list of attributes, EX: attr1,attr2}

By default, the API will show a subset of the available attributes for a given media type.
This behavior can be overridden by providing include=all to show all attributes
or include=attribute1,attribute2 to include a specific list. The API is optimized
to return the default values, so overriding this can impact the performance of your request.

The include=all option is most useful for testing in the browser. Use it to identify
the set of attributes required and use only those by passing them as a comma separated
list, e.g. include=prefLabel,cui.

The include parameter is currently unsupported on Annotator and Recommender endpoints.

format

json
jsonp
xml

The API returns JSON as the default content type. This can be overridden by using the format
query string parameter. The API also respects Accept header entries, with precedence given
to the format parameter.

page

{integer representing the page number}

For calls that are paged, this will indicate which page number you want to retrieve.
You can follow hypermedia links for nextPage and prevPage as well.

pagesize

{integer representing the size of the returned page}

For calls that are paged, this will indicate the size of the page you want to retrieve.

include_views

{boolean representing whether or not to include ontology views (default is false)}

For calls that involve ontologies, include_views='true' will include ontology views.

display_context

{true|false} (defaults to true)

Turn off the JSON-LD context serialization. This will reduce the response size significantly for some calls, speeding up transmission and parse time.

display_links

{true|false} (defaults to true)

Turn off the hypermedia link serialization. This will reduce the response size significantly for some calls, speeding up transmission and parse time.

download_format

{csv|rdf} (defaults to user-uploaded file format)

Allows you to specify alternative formats for ontology file downloads for ontology and ontology submission download endpoints. CSV is only available for the most recent submission.

Search, Annotator, Recommender, and Resource Index Endpoints

Several endpoints are available for performing lookups for classes, annotations, and annotated resources. These endpoints are not strictly RESTful, but do return objects with links where relevant.

pagesize={integer representing the size of the returned page} // default = 50

Subtree Search

The same endpoint also allows limiting a search to a given subtree/branch. The root of the subtree is defined using a combination of parameters "ontology" and "subtree_root_id". Both are required when performing a subtree search.

expand_semantic_types_hierarchy={true|false} // default = false. true means to use the semantic types passed in the "semantic_types" parameter as well as all their immediate children. false means to use ONLY the semantic types passed in the "semantic_types" parameter.

expand_class_hierarchy={true|false} // default = false. used only in conjunction with "class_hierarchy_max_level" parameter; determines whether or not to include ancestors of the given class when performing an annotation.

class_hierarchy_max_level={0..N} // default = 0. the depth of the hierarchy to use when performing an annotation.

expand_mappings={true|false} // default = false. true means that the following manual mappings will be used in annotation: UMLS, REST, CUI, OBOXREF.

stop_words={word1,word2..,wordN} (case insensitive)

minimum_match_length={0..N}

exclude_numbers={true|false} // default = false

whole_word_only={true|false} // default = true

exclude_synonyms={true|false} // default = false

longest_only={true|false} // default = false. true means that only the longest match for a given phrase will be returned.

Suggest ontologies for the text "Melanoma is a malignant tumor of melanocytes which are found predominantly in skin but also in the bowel and the eye", limiting the evaluation to ontology coverage (the weights for the other criteria -acceptance, detail and specialization- will be set to 0):

Resources

Batch Endpoints

In order to reduce the number of HTTP requests required to obtain information about resources, we are exploring
the use of batch endpoints that will use one request/response cycle for multiple resources. Currently, only
classes are supported.

POST/batch

The batch service takes input in the BODY of a POST request. The input should be a JSON document with the following structure:

Single Ontology Analytics

Resource Endpoints

Endpoints for RESTful resources can be found below, specifically in the list of Media Types.
Using the provided hypermedia links, you can navigate from resource to resource.
Each Media Type has a corresponding collection URL (when available), a list of HTTP verbs that can
be used to operate on the resources, a description of the resource (including available attributes),
and a list of hypermedia links that can be found on each resource.

Media Types and Hypermedia Links

Documentation

The documentation below describes the media types that available in the API and the hypermedia links that connect them.
Media types describe the types of resources available, including the HTTP verbs that may be used with them and the
attributes that each resource contains.

Hypermedia Links

This programming interface comprises HTTP commands that return objects that themselves contain links to other locations
in the form of a URL.
In addition to the actual return values, the returned objects contain a set of links to related information.
You can access these links using HTTP commands, typically GET. Thus, it is possible to traverse BioPortal's information for
an ontology, including classes, notes, and reviews, by starting from the list of ontologies and traversing the available
links - either programmatically or in a browser. The different resources are described below, including information about
their available attributes, links, and the HTTP verbs that can be used to interact with them.

HTTP Verbs

The API uses different verbs to support processing of resources. This includes things like creating or deleting
individual resources or something more specific searching or annotating. Typically, the verbs will be used in
conjunciton with the URL that represents the id for a given resource. Here is how we interpret the verbs:

GET Used to retreive a resource or collection of resources.

POST Used to create a resource when the server determines the resource's id.

PUT Used to create a resource when a client determines the resource's id.

PATCH Used to modify an existing resource. The attributes in a PATCH request will replace existing attributes.

Content Types

The API returns JSON as the default content type. This can be overridden by using the format
query string parameter with the value json, jsonp, or xml. The API also respects Accept header entries
(EX: application/json, application/xml), with precedence given to the format parameter.

JSON

The default content type is JSON, specifically a variant called JSON-LD,
or JSON Linked Data. You can treat this variant like normal JSON. All JSON parsers will be able
to parse the output normally. The benefit of JSON-LD is that it enables hypermedia links, and you
will find these links exposed as URLs in attributes labeled @id, which correspond to the id of the
parent resource, or in an array called links, which contains a hash of link types with corresponding URLs.

Line 7 shows the id for the resource. Doing an HTTP GET on the id will retreive the resource.

Line 8 shows the media type (see below).

Line 9 starts the links hash.

Line 16 is the resource's context, which can be used to determine the type for lists of ids. For example, line 2 lists
the ids for users who administer the ontology, which can be determined by looking for the administeredBy attribute
in the @context hash.

If you are interested in the predicate URI values used in the resource, these can be deterined by looking up the
attribute in the @context hash or by appending the value of @vocab (line 17) to an attribute name in cases where
the attribute isn't listed specifically in the @context.