API Documentation

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:

  1. Using the apikey query string parameter
  2. Providing an Authorization header: Authorization: apikey token=your_apikey (replace `your_apikey` with your actual key)
  3. 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.

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.

An endpoint for searching terms and their properties is available

  • Perform search
  • Parameters
    • ontologies={ontology_id1,ontology_id2,ontology_id3}
    • require_exact_match={true|false} // default = false
    • suggest={true|false} // default = false. Will perform a search specifically geared towards type-ahead suggestions.
    • also_search_views={true|false} // Include ontology views in the search. default = false
    • require_definitions={true|false} // default = false
    • also_search_properties={true|false} // default = false
    • also_search_obsolete={true|false} // default = false (exclude obsolete terms)
    • cui={C0018787,C0225807,C0018787} // Allows restricting query by CUIs. default = null (no restriction)
    • semantic_types={T023,T185,T061} // Allows restricting query by Semantic Types (TUI). default = null (no restriction)
    • include={prefLabel, synonym, definition, notation, cui, semanticType} // default = (see Common Parameters section)
    • page={integer representing the page number} // default = 1
    • pagesize={integer representing the size of the returned page} // default = 50

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.

The same endpoint allows limiting a search to root classes only.

An endpoint for searching ontology properties by their labels and IDs (URIs)

  • Perform search
  • Parameters
    • ontologies={ontology_id1,ontology_id2,ontology_id3}
    • require_exact_match={true|false} // Restricts results only to the exact matches of the query by the property id, label, or the generated label (a label, auto-generated from the ID). default = false
    • also_search_views={true|false} // Include ontology views in the search. default = false
    • require_definitions={true|false} // Filter results only to those that include definitions. default = false
    • include={label, labelGenerated, definition, parents} // default = All of the properties in this example
    • ontology_types={ONTOLOGY,VALUE_SET_COLLECTION} // default = all ontology types are returned
    • property_types={object,annotation,datatype} // Restricts results to specific property types (object, annotation, datatype). default = all property types are returned
    • page={integer representing the page number} // default = 1
    • pagesize={integer representing the size of the returned page} // default = 50

The Annotator endpoint will examine text input and return relevant classes.

  • Annotate text
  • Parameters
    • Filtering & query behavior
      • ontologies={ontology_id1,ontology_id2..,ontology_idN}
      • semantic_types={semType1,semType2..,semTypeN}
      • 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.
  • Default stop words
    • The following stop words are used by default:
      • I, a, above, after, against, all, alone, always, am, amount, an, and, any, are, around, as, at, back, be, before, behind, below, between, bill, both, bottom, by, call, can, co, con, de, detail, do, done, down, due, during, each, eg, eight, eleven, empty, ever, every, few, fill, find, fire, first, five, for, former, four, from, front, full, further, get, give, go, had, has, hasnt, he, her, hers, him, his, i, ie, if, in, into, is, it, last, less, ltd, many, may, me, mill, mine, more, most, mostly, must, my, name, next, nine, no, none, nor, not, nothing, now, of, off, often, on, once, one, only, or, other, others, out, over, part, per, put, re, same, see, serious, several, she, show, side, since, six, so, some, sometimes, still, take, ten, the, then, third, this, thick, thin, three, through, to, together, top, toward, towards, twelve, two, un, under, until, up, upon, us, very, via, was, we, well, when, while, who, whole, will, with, within, without, you, yourself, yourselves

The Recommender endpoint receives a text or a list of keywords and suggests appropriate ontologies for them.

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:

{
    "http://www.w3.org/2002/07/owl#Class": {
        "collection": [
            {
                "class": "http://example.org/ontology1/class1",
                "ontology": "http://example.org/ontology1"
            },
            {
                "class": "http://example.org/ontology2/class1",
                "ontology": "http://example.org/ontology2"
            },
            {
                "class": "http://example.org/ontologyN/classN",
                "ontology": "http://example.org/ontologyN"
            }
        ],
        "display": "prefLabel,synonym,semanticTypes"
    }
}

Example:

{
    "http://www.w3.org/2002/07/owl#Class": {
        "collection": [
            {
                "class": "http://bioontology.org/ontologies/BiomedicalResourceOntology.owl#Ontology_Development_and_Management",
                "ontology": "http://data.bioontology.org/ontologies/BRO"
            },
            {
              "class": "http://bioontology.org/ontologies/BiomedicalResourceOntology.owl#Modular_Component",
                "ontology": "http://data.bioontology.org/ontologies/BRO"
            },
            {
              "class": "http://bioontology.org/ontologies/BiomedicalResourceOntology.owl#Stimulator",
                "ontology": "http://data.bioontology.org/ontologies/BRO"
            }
        ],
        "display": "prefLabel,synonym,semanticTypes"
    }
}

An endpoint for retrieving ontology visitor stats provided by Google Analytics.

Allows to retrieve analytics for all ontologies for a specific month/year combination

  • Get ALL analytics data
  • Get analytics data for a given month/year
  • Parameters
    • month={1-12}
    • year={2013-...}

Allows to retrieve ALL analytics data for a single ontology

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.

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.
  • DELETE Used to delete an existing resource.

Available Media Types

  1. http://data.bioontology.org/metadata/Category
  2. http://www.w3.org/2002/07/owl#Class
  3. http://data.bioontology.org/metadata/Group
  4. http://www.w3.org/2002/07/owl#NamedIndividual
  5. http://data.bioontology.org/metadata/Mapping
  6. http://data.bioontology.org/metadata/Metrics
  7. http://data.bioontology.org/metadata/Note
  8. http://data.bioontology.org/metadata/Reply
  9. http://www.w3.org/2002/07/owl#ObjectProperty
  10. http://data.bioontology.org/metadata/Ontology
  11. http://data.bioontology.org/metadata/OntologySubmission
  12. http://data.bioontology.org/metadata/Project
  13. http://data.bioontology.org/metadata/ProvisionalClass
  14. http://data.bioontology.org/metadata/ProvisionalRelation
  15. http://data.bioontology.org/metadata/Review
  16. http://www.w3.org/2004/02/skos/core#Collection
  17. http://www.w3.org/2004/02/skos/core#ConceptScheme
  18. http://data.bioontology.org/metadata/Slice
  19. http://data.bioontology.org/metadata/User

http://data.bioontology.org/metadata/Category

HTTP Methods for Resource

HTTP Verb Path
GET /ontologies/:acronym/categories
GET /categories
GET /categories/:acronym
PUT /categories/:acronym
POST /categories
PATCH /categories/:acronym
DELETE /categories/:acronym

Resource Description

Attribute Default Unique Required List Type
acronym true true true    
name true   true    
description true        
created true        
parentCategory true       http://data.bioontology.org/metadata/Category 
ontologies true       http://data.bioontology.org/metadata/Ontology 

http://www.w3.org/2002/07/owl#Class

HTTP Methods for Resource

HTTP Verb Path
GET /ontologies/:ontology/classes
GET /ontologies/:ontology/classes/roots_paged
GET /ontologies/:ontology/classes/roots
GET /ontologies/:ontology/classes/:cls
GET /ontologies/:ontology/classes/:cls/paths_to_root
GET /ontologies/:ontology/classes/:cls/tree
GET /ontologies/:ontology/classes/:cls/ancestors
GET /ontologies/:ontology/classes/:cls/descendants
GET /ontologies/:ontology/classes/:cls/children
GET /ontologies/:ontology/classes/:cls/parents

Resource Description

Attribute Default Unique Required List Type
prefLabel true   true    
synonym true     true  
definition true     true  
obsolete true        
semanticType true     true  
cui true     true  
inScheme true     true  
memberOf true       http://www.w3.org/2004/02/skos/core#Collection 
created true        
modified true        
label       true  
prefLabelXl       true http://www.w3.org/2008/05/skos-xl#Label 
altLabelXl       true http://www.w3.org/2008/05/skos-xl#Label 
hiddenLabelXl       true http://www.w3.org/2008/05/skos-xl#Label 
notation          
prefixIRI          
parents       true http://www.w3.org/2002/07/owl#Class 
ancestors         http://www.w3.org/2002/07/owl#Class 
children         http://www.w3.org/2002/07/owl#Class 
subClassOf       true  
xref          
notes         http://data.bioontology.org/metadata/Note 
properties          
childrenCount          
hasChildren          

Related Hypermedia Links

Type URL
self https://data.bioportal.lirmm.fr/ontologies/BRO/classes/http%3A%2F%2Fbioontology.org%2Fontologies%2FBiomedicalResourceOntology.owl%23Ontology_Development_and_Management
ontology https://data.bioportal.lirmm.fr/ontologies/BRO
children https://data.bioportal.lirmm.fr/ontologies/BRO/classes/http%3A%2F%2Fbioontology.org%2Fontologies%2FBiomedicalResourceOntology.owl%23Ontology_Development_and_Management/children
parents https://data.bioportal.lirmm.fr/ontologies/BRO/classes/http%3A%2F%2Fbioontology.org%2Fontologies%2FBiomedicalResourceOntology.owl%23Ontology_Development_and_Management/parents
descendants https://data.bioportal.lirmm.fr/ontologies/BRO/classes/http%3A%2F%2Fbioontology.org%2Fontologies%2FBiomedicalResourceOntology.owl%23Ontology_Development_and_Management/descendants
ancestors https://data.bioportal.lirmm.fr/ontologies/BRO/classes/http%3A%2F%2Fbioontology.org%2Fontologies%2FBiomedicalResourceOntology.owl%23Ontology_Development_and_Management/ancestors
instances https://data.bioportal.lirmm.fr/ontologies/BRO/classes/http%3A%2F%2Fbioontology.org%2Fontologies%2FBiomedicalResourceOntology.owl%23Ontology_Development_and_Management/instances
tree https://data.bioportal.lirmm.fr/ontologies/BRO/classes/http%3A%2F%2Fbioontology.org%2Fontologies%2FBiomedicalResourceOntology.owl%23Ontology_Development_and_Management/tree
notes https://data.bioportal.lirmm.fr/ontologies/BRO/classes/http%3A%2F%2Fbioontology.org%2Fontologies%2FBiomedicalResourceOntology.owl%23Ontology_Development_and_Management/notes
mappings https://data.bioportal.lirmm.fr/ontologies/BRO/classes/http%3A%2F%2Fbioontology.org%2Fontologies%2FBiomedicalResourceOntology.owl%23Ontology_Development_and_Management/mappings
ui http://bioportal.lirmm.fr/ontologies/BRO?p=classes&conceptid=http%3A%2F%2Fbioontology.org%2Fontologies%2FBiomedicalResourceOntology.owl%23Ontology_Development_and_Management

http://data.bioontology.org/metadata/Group

HTTP Methods for Resource

HTTP Verb Path
GET /ontologies/:acronym/groups
GET /groups
GET /groups/:acronym
PUT /groups/:acronym
POST /groups
PATCH /groups/:acronym
DELETE /groups/:acronym

Resource Description

Attribute Default Unique Required List Type
acronym true true true    
name true   true    
description true        
created true        
ontologies true       http://data.bioontology.org/metadata/Ontology 

http://www.w3.org/2002/07/owl#NamedIndividual

HTTP Methods for Resource

HTTP Verb Path
GET /ontologies/:ontology/classes/:cls/instances
GET /ontologies/:ontology/instances
GET /ontologies/:ontology/instances/:inst

Resource Description

Attribute Default Unique Required List Type
label true     true  
prefLabel true   true    
types true     true  
properties true        

http://data.bioontology.org/metadata/Mapping

HTTP Methods for Resource

HTTP Verb Path
GET /ontologies/:ontology/classes/:cls/mappings
GET /ontologies/:ontology/mappings
GET /mappings
GET /mappings/recent
GET /mappings/:mapping
GET /mappings/statistics/ontologies
GET /mappings/statistics/ontologies/:ontology
GET /mappings/statistics/interportal/:ontology
GET /mappings/statistics/external
POST /mappings
POST /mappings/load
PATCH /mappings/:mapping
DELETE /mappings/:mapping

Resource Description

Attribute Default Unique Required List Type
process          
classes          
id          
source          

http://data.bioontology.org/metadata/Metrics

HTTP Methods for Resource

HTTP Verb Path
GET /metrics
GET /metrics/missing
GET /ontologies/:ontology/metrics
GET /ontologies/:ontology/submissions/:ontology_submission_id/metrics

Resource Description

Attribute Default Unique Required List Type
submission true       http://data.bioontology.org/metadata/OntologySubmission 
created true        
classes true   true    
individuals true   true    
properties true   true    
maxDepth true   true    
maxChildCount true   true    
averageChildCount true   true    
classesWithOneChild true   true    
classesWithMoreThan25Children true   true    
classesWithNoDefinition true   true    

http://data.bioontology.org/metadata/Note

HTTP Methods for Resource

HTTP Verb Path
GET /ontologies/:ontology/notes?:include_threads?
GET /ontologies/:ontology/classes/:cls/notes?:include_threads?
GET /notes?:include_threads?
GET /notes/:noteid?:include_threads?
POST /notes
PATCH /notes/:noteid
DELETE /notes/:noteid

Resource Description

Attribute Default Unique Required List Type
subject true        
body true        
creator true   true   http://data.bioontology.org/metadata/User 
created true        
archived true        
createdInSubmission true       http://data.bioontology.org/metadata/OntologySubmission 
reply true     true http://data.bioontology.org/metadata/Reply 
relatedOntology true   true true http://data.bioontology.org/metadata/Ontology 
relatedClass true     true http://www.w3.org/2002/07/owl#Class 
proposal true       http://data.bioontology.org/metadata/Base 

http://data.bioontology.org/metadata/Reply

HTTP Methods for Resource

HTTP Verb Path
GET /notes/:noteid/replies
GET /replies?:include_threads?
GET /replies/:replyid
POST /replies
PATCH /replies/:replyid
DELETE /replies/:replyid

Resource Description

Attribute Default Unique Required List Type
body true   true    
creator true   true   http://data.bioontology.org/metadata/User 
created true        
children true       http://data.bioontology.org/metadata/Reply 
parent         http://data.bioontology.org/metadata/Reply 

http://www.w3.org/2002/07/owl#ObjectProperty

HTTP Methods for Resource

HTTP Verb Path
GET /ontologies/:ontology/properties
GET /ontologies/:ontology/properties/roots
GET /ontologies/:ontology/properties/:property
GET /ontologies/:ontology/properties/:property/label
GET /ontologies/:ontology/properties/:property/tree
GET /ontologies/:ontology/properties/:property/ancestors
GET /ontologies/:ontology/properties/:property/descendants
GET /ontologies/:ontology/properties/:property/parents
GET /ontologies/:ontology/properties/:property/children

Resource Description

Attribute Default Unique Required List Type
label true     true  
definition true     true  
parents true     true http://www.w3.org/2002/07/owl#ObjectProperty 
children true       http://www.w3.org/2002/07/owl#ObjectProperty 
submission          
ancestors          
descendants          

http://data.bioontology.org/metadata/Ontology

HTTP Methods for Resource

HTTP Verb Path
GET /ontologies
GET /ontologies/:acronym
GET /ontologies/:acronym/latest_submission
GET /ontologies/:acronym/download
GET /ontologies_full
PUT /ontologies/:acronym
POST /ontologies
PATCH /ontologies/:acronym/latest_submission
PATCH /ontologies/:acronym
DELETE /ontologies/:acronym

Resource Description

Attribute Default Unique Required List Type
acronym true true true    
name true true true    
administeredBy true   true true http://data.bioontology.org/metadata/User 
group true     true http://data.bioontology.org/metadata/Group 
viewingRestriction true        
flat true        
hasDomain true     true http://data.bioontology.org/metadata/Category 
summaryOnly true        
viewOf true       http://data.bioontology.org/metadata/Ontology 
views true       http://data.bioontology.org/metadata/Ontology 
ontologyType true       http://data.bioontology.org/metadata/OntologyType 
submissions         http://data.bioontology.org/metadata/OntologySubmission 
projects         http://data.bioontology.org/metadata/Project 
notes         http://data.bioontology.org/metadata/Note 
reviews         http://data.bioontology.org/metadata/Review 
provisionalClasses         http://data.bioontology.org/metadata/ProvisionalClass 
subscriptions         http://data.bioontology.org/metadata/Subscription 
doNotUpdate          
acl       true http://data.bioontology.org/metadata/User 

Related Hypermedia Links

Type URL
submissions https://data.bioportal.lirmm.fr/ontologies/BRO/submissions
properties https://data.bioportal.lirmm.fr/ontologies/BRO/properties
classes https://data.bioportal.lirmm.fr/ontologies/BRO/classes
single_class https://data.bioportal.lirmm.fr/ontologies/BRO/classes/{class_id}
roots https://data.bioportal.lirmm.fr/ontologies/BRO/classes/roots
schemes https://data.bioportal.lirmm.fr/ontologies/BRO/schemes
collections https://data.bioportal.lirmm.fr/ontologies/BRO/collections
xl_labels https://data.bioportal.lirmm.fr/ontologies/BRO/skos_xl_labels
instances https://data.bioportal.lirmm.fr/ontologies/BRO/instances
metrics https://data.bioportal.lirmm.fr/ontologies/BRO/metrics
reviews https://data.bioportal.lirmm.fr/ontologies/BRO/reviews
notes https://data.bioportal.lirmm.fr/ontologies/BRO/notes
groups https://data.bioportal.lirmm.fr/ontologies/BRO/groups
categories https://data.bioportal.lirmm.fr/ontologies/BRO/categories
latest_submission https://data.bioportal.lirmm.fr/ontologies/BRO/latest_submission
projects https://data.bioportal.lirmm.fr/ontologies/BRO/projects
download https://data.bioportal.lirmm.fr/ontologies/BRO/download
views https://data.bioportal.lirmm.fr/ontologies/BRO/views
analytics https://data.bioportal.lirmm.fr/ontologies/BRO/analytics
ui http://bioportal.lirmm.fr/ontologies/BRO

http://data.bioontology.org/metadata/OntologySubmission

HTTP Methods for Resource

HTTP Verb Path
GET /submissions
GET /ontologies/:acronym/submissions
GET /ontologies/:acronym/submissions/:ontology_submission_id
GET /ontologies/:acronym/submissions/:ontology_submission_id/download
GET /ontologies/:acronym/submissions/:ontology_submission_id/download_diff
POST /submissions
POST /ontologies/:acronym/submissions
PATCH /ontologies/:acronym/submissions/:ontology_submission_id
DELETE /ontologies/:acronym/submissions/:ontology_submission_id

Resource Description

Attribute Default Unique Required List Type
submissionId true   true    
hasOntologyLanguage true   true   http://data.bioontology.org/metadata/OntologyFormat 
homepage true        
publication true        
documentation true        
version true        
description true        
status true        
contact true   true true http://data.bioontology.org/metadata/Contact 
creationDate true        
released true   true    
ontology true   true   http://data.bioontology.org/metadata/Ontology 
prefLabelProperty          
definitionProperty          
synonymProperty          
authorProperty          
classType          
hierarchyProperty          
obsoleteProperty          
obsoleteParent          
URI          
naturalLanguage       true  
numberOfClasses          
numberOfIndividuals          
numberOfProperties          
maxDepth          
maxChildCount          
averageChildCount          
classesWithOneChild          
classesWithMoreThan25Children          
classesWithNoDefinition          
modificationDate          
entities          
numberOfAxioms          
keyClasses          
keywords          
knownUsage          
notes          
conformsToKnowledgeRepresentationParadigm          
hasContributor          
hasCreator          
designedForOntologyTask       true  
wasGeneratedBy          
wasInvalidatedBy          
curatedBy          
endorsedBy       true  
fundedBy          
translator          
hasDomain          
hasFormalityLevel          
hasLicense          
hasOntologySyntax          
isOfType          
usedOntologyEngineeringMethodology          
usedOntologyEngineeringTool          
useImports       true  
hasPriorVersion          
isBackwardCompatibleWith       true  
isIncompatibleWith       true  
deprecated          
versionIRI          
ontologyRelatedTo       true  
comesFromTheSameDomain       true  
similarTo       true  
isAlignedTo       true  
explanationEvolution          
generalizes          
hasDisparateModelling          
hiddenLabel          
coverage          
publisher          
identifier          
source          
abstract          
alternative          
hasPart          
isFormatOf          
hasFormat          
audience          
valid          
accrualMethod          
accrualPeriodicity          
accrualPolicy          
endpoint          
dataDump          
csvDump          
openSearchDescription          
uriLookupEndpoint          
uriRegexPattern          
depiction          
logo          
competencyQuestion          
usedBy       true  
metadataVoc       true  
hasDisjunctionsWith          
toDoList          
example          
preferredNamespaceUri          
preferredNamespacePrefix          
morePermissions          
useGuidelines          
curatedOn          
repository          
bugDatabase          
mailingList          
exampleIdentifier          
award          
copyrightHolder          
associatedMedia          
workTranslation          
translationOfWork          
includedInDataCatalog       true  
uploadFilePath          
diffFilePath          
masterFileName          
submissionStatus       true http://data.bioontology.org/metadata/SubmissionStatus 
missingImports       true  
pullLocation          
metrics         http://data.bioontology.org/metadata/Metrics 

http://data.bioontology.org/metadata/Project

HTTP Methods for Resource

HTTP Verb Path
GET /ontologies/:acronym/projects
GET /projects
GET /projects/:acronym
PUT /projects/:acronym
POST /projects
PATCH /projects/:acronym
DELETE /projects/:acronym

Resource Description

Attribute Default Unique Required List Type
acronym true true true    
creator true   true true http://data.bioontology.org/metadata/User 
created true        
updated true        
name true   true    
homePage true   true    
description true   true    
contacts true        
institution true        
ontologyUsed true     true http://data.bioontology.org/metadata/Ontology 

http://data.bioontology.org/metadata/ProvisionalClass

HTTP Methods for Resource

HTTP Verb Path
GET /ontologies/:ontology/provisional_classes
GET /users/:user/provisional_classes
GET /provisional_classes
GET /provisional_classes/:provisional_class_id
POST /provisional_classes
PATCH /provisional_classes/:provisional_class_id
DELETE /provisional_classes/:provisional_class_id

Resource Description

Attribute Default Unique Required List Type
label true   true    
synonym true     true  
definition true     true  
subclassOf true        
creator true   true   http://data.bioontology.org/metadata/User 
created true        
permanentId true        
noteId true        
ontology true       http://data.bioontology.org/metadata/Ontology 
relations true       http://data.bioontology.org/metadata/ProvisionalRelation 

http://data.bioontology.org/metadata/ProvisionalRelation

HTTP Methods for Resource

HTTP Verb Path
GET /provisional_relations
GET /provisional_relations/:provisional_relation_id
POST /provisional_relations
DELETE /provisional_relations/:provisional_relation_id

Resource Description

Attribute Default Unique Required List Type
source true   true   http://data.bioontology.org/metadata/ProvisionalClass 
relationType true   true    
targetClassId true   true    
targetClassOntology true   true   http://data.bioontology.org/metadata/Ontology 
creator true   true   http://data.bioontology.org/metadata/User 
created true        

http://data.bioontology.org/metadata/Review

HTTP Methods for Resource

HTTP Verb Path
GET /ontologies/:acronym/reviews
GET /reviews
GET /reviews/:review_id
POST /reviews
PATCH /reviews/:review_id
DELETE /reviews/:review_id

Resource Description

Attribute Default Unique Required List Type
creator true   true   http://data.bioontology.org/metadata/User 
created true        
updated true        
body true   true    
ontologyReviewed true   true   http://data.bioontology.org/metadata/Ontology 
usabilityRating true        
coverageRating true        
qualityRating true        
formalityRating true        
correctnessRating true        
documentationRating true        

http://www.w3.org/2004/02/skos/core#Collection

HTTP Methods for Resource

HTTP Verb Path
GET /ontologies/:ontology/collections
GET /ontologies/:ontology/collections/:collection
GET /ontologies/:ontology/collections/:collection/members

Resource Description

Attribute Default Unique Required List Type
prefLabel true   true    
memberCount true        
properties          

http://www.w3.org/2004/02/skos/core#ConceptScheme

HTTP Methods for Resource

HTTP Verb Path
GET /ontologies/:ontology/schemes
GET /ontologies/:ontology/schemes/:scheme

Resource Description

Attribute Default Unique Required List Type
prefLabel true   true    
properties true        

http://data.bioontology.org/metadata/Slice

HTTP Methods for Resource

HTTP Verb Path
GET /slices
GET /slices/synchronize_groups
GET /slices/:slice_id
POST /slices
PATCH /slices/:slice
DELETE /slices/:slice

Resource Description

Attribute Default Unique Required List Type
acronym true true true    
name true   true    
description true        
created true        
ontologies true   true true http://data.bioontology.org/metadata/Ontology 

http://data.bioontology.org/metadata/User

HTTP Methods for Resource

HTTP Verb Path
GET /users
GET /users/:username
PUT /users/:username
POST /users/authenticate
POST /users/create_reset_password_token
POST /users/reset_password
POST /users
PATCH /users/:username
DELETE /users/:username

Resource Description

Attribute Default Unique Required List Type
username true true true    
email true   true    
role true     true http://data.bioontology.org/metadata/Role 
apikey true true      
firstName          
lastName          
githubId   true      
orcidId   true      
created          
subscription       true http://data.bioontology.org/metadata/Subscription 
customOntology       true http://data.bioontology.org/metadata/Ontology 
provisionalClasses         http://data.bioontology.org/metadata/ProvisionalClass 

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.

Here is a sample output of the JSON response format:

{
    "administeredBy": [
        "http://data.bioontology.org/user/nevada"
    ],
    "acronym": "ABA-API-TST",
    "name": "ABA Adult Mouse Brain",
    "@id": "http://data.bioontology.org/ontology/ABA-API-TST",
    "@type": "http://data.bioontology.org/metadata/Ontology",
    "links": {
        "metrics": "http://data.bioontology.org/ontologies/ABA-API-TST/metrics",
        "submissions": "http://data.bioontology.org/ontologies/ABA-API-TST/submissions",
        "classes": "http://data.bioontology.org/ontologies/ABA-API-TST/classes",
        "roots": "http://data.bioontology.org/ontologies/ABA-API-TST/classes/roots",
        "reviews": "http://data.bioontology.org/ontologies/ABA-API-TST/reviews"
    },
    "@context": {
        "@vocab": "http://data.bioontology.org/metadata/",
        "acronym": "http://omv.ontoware.org/2005/05/ontology#acronym",
        "name": "http://omv.ontoware.org/2005/05/ontology#name",
        "administeredBy": {
            "@id": "http://data.bioontology.org/metadata/User",
            "@type": "@id"
        }
    }
}

  • 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.

XML

XML is also available as an alternative content type.

Here is sample output for the XML format:

<ontology>
  <administeredByCollection>
    <administeredBy>http://data.bioontology.org/user/nevada</administeredBy>
  </administeredByCollection>
  <acronym>ABA-API-TST</acronym>
  <name>ABA Adult Mouse Brain</name>
  <id>http://data.bioontology.org/ontology/ABA-API-TST</id>
  <links>
    <self href="http://data.bioontology.org/ontology/ABA-API-TST" rel="http://data.bioontology.org/metadata/Ontology"/>
    <metrics href="/ontologies/ABA-API-TST/metrics"/>
    <submissions href="/ontologies/ABA-API-TST/submissions" rel="http://data.bioontology.org/metadata/OntologySubmission"/>
    <classes href="/ontologies/ABA-API-TST/classes" rel="http://www.w3.org/2002/07/owl#Class"/>
    <roots href="/ontologies/ABA-API-TST/classes/roots" rel="http://www.w3.org/2002/07/owl#Class"/>
    <reviews href="/ontologies/ABA-API-TST/reviews" rel="http://data.bioontology.org/metadata/Review"/>
  </links>
</ontology>
  • Line 8 starts the links section
  • Lines 9-14 list links by type. The href attribute contains the link location and the rel attribute defines the type of resource that will be found at that location.
  • Elements outside of the links can also contain href and rel attributes (coming soon...)