BioPortal Provisional Terms

Provisional Term Usage

When a BioPortal user creates a new term proposal for an ontology, BioPortal also automatically creates a provisional id for the proposed term. This id can be used to represent the term while the term proposal is under review by the ontology authors.

Eventually, if the term is implemented in the requested ontology, the permanent id for the term will be recorded in the proposal and in the provisional term record. The provisional term id can then be used to see the permanent id, preferred name, synonyms, and definition in addition to the provisional information.

This feature is planned for release April 27, 2011.

• Note: All NCBO Web services will be required to contain the parameter "apikey=YourApiKey" starting June 2011. The parameter will be added to all Web service calls for the April 27, 2011 release but will not be required until June 2011. To obtain an API key, login to BioPortal and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

• Note for Application Developers: Application developers will also need to include the apikey parameter on all NCBO Web service calls. This allows us to track usage of our system at the level of an application. To obtain an API key, login to BioPortal and go to "Account" where your API key will be displayed. The addition of the API key replaces the use of the email parameter.

Provisional Term Service

Get a single provisional term

• Description: Get a single provisional term for the given provisional term id.
• Signature: ./provisional?termid={term_id}&apikey={YourAPIKey}
• Example: http://stagerest.bioontology.org/bioportal/provisional?termid=http%3A%2F%2Fpurl.bioontology.org%2Fontology%2Fprovisional%2Fba477936-36a5-465b-9224-f4b95ea69e64&apikey=YourAPIKey

Get all provisional terms

• Description: Get all available provisional terms using a paged interface.
• Signature: ./provisional?apikey={YourAPIKey}
• Example: http://rest.bioontology.org/bioportal/provisional?apikey=YourAPIKey

The following parameters can be used to filter the result set:

• pagesize={page size} - limits how many results to return per call. Default: 1000. Max: 50,000.
• pagenum={page number} - which page of results to return. Default: 1.
• submittedby={BioPortal user id} - filters by given user id. Multiple ids can be passed as a comma-separated list.
• createdstartdate={ISO 8601 combined date/time. EX: 2010-10-24T18:00:00Z.} - filter by date range. If provided by itself, BioPortal assumes the range should end with the current date and time.
• createdenddate={ISO 8601 combined date/time. EX: 2010-10-24T18:00:00Z.} - filter by date range. Optional, can be used with createdstartdate to limit results to a particular range.
• updatedstartdate={ISO 8601 combined date/time. EX: 2010-10-24T18:00:00Z.} - filter by date range. If provided by itself, BioPortal assumes the range should end with the current date and time.
• updatedenddate={ISO 8601 combined date/time. EX: 2010-10-24T18:00:00Z.} - filter by date range. Optional, can be used with updatedstartdate to limit results to a particular range.
• ontologyids={ontology virtual id} - limits terms to those created on a particular ontology. Can be a single id or a comma-separated list.
• implementedtermsonly={true|false} - when set to 'true' the service only returns terms that have been implemented, which is determined by looking for an associated permanent id.

Create a provisional term

• Description: Create a provisional term.
• Signature (HTTP POST): ./provisional?apikey={YourAPIKey}
• Parameters (* required)
  • * preferredname={preferred name/label}
  • * ontologyids={ontology virtual id(s)} - ontologies that might be interested in implementing the proposed term.
  • * definition={definition} - definition for the proposed term.
  • * submittedby={BioPortal user id} - records the user id of the submitter. This can be an individual user or the user account for an application that is submitting requests on behalf of its users.
  • superclass={URI for term} - the proposed parent class for the proposed term.

Update an existing provisional term

• Description: Get all available provisional terms using a paged interface.
• Signature (HTTP PUT): ./provisional?apikey={YourAPIKey}
• Parameters (* required)
  • * termid={URI for term}
  • preferredname={preferred name/label}
  • ontologyids={ontology virtual id(s)} - ontologies that might be interested in implementing the proposed term.
  • definition={definition} - definition for the proposed term.
  • submittedby={BioPortal user id} - records the user id of the submitter. This can be an individual user or the user account for an application that is submitting requests on behalf of its users.
  • superclass={URI for term} - the proposed parent class for the proposed term.
  • permanentid={URI for term} - records the id for the term if/when it has been implemented by an ontology.

Delete an existing provisional term

• Description: Get all available provisional terms using a paged interface.
• Signature (HTTP DELETE): ./provisional?apikey={YourAPIKey}
• Parameters (* required)
  • * termid={URI for term}