Difference between revisions of "BioPortal Provisional Terms"

From NCBO Wiki
Jump to navigation Jump to search
 
(26 intermediate revisions by 2 users not shown)
Line 3: Line 3:
  
 
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.
 
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.
 +
 +
* '''<font color='red'>Note</font>''': 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 =
 
= Provisional Term Service =
Line 8: Line 14:
 
== Get a single provisional term ==
 
== Get a single provisional term ==
 
* '''Description''': Get a single provisional term for the given provisional term id.
 
* '''Description''': Get a single provisional term for the given provisional term id.
−
* '''Signature''': /provisional?termid={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
+
* '''Example''': http://rest.bioontology.org/bioportal/provisional?termid=http://purl.bioontology.org/ontology/provisional/8e06127d-df18-477b-88ef-fca750f370ad&apikey=YourAPIKey
  
−
== Get all provisional terms (filtered using parameters below) ==
+
== Get all provisional terms ==
 
* '''Description''': Get all available provisional terms using a paged interface.
 
* '''Description''': Get all available provisional terms using a paged interface.
−
* '''Signature''': /provisional
+
* '''Signature''': ./provisional?apikey={YourAPIKey}
−
* '''Example''': http://stagerest.bioontology.org/bioportal/provisional
+
* '''Example''': http://rest.bioontology.org/bioportal/provisional?apikey=YourAPIKey
  
−
The following parameters can be used to filter the result set:
+
The following <font color="red">''parameters can be used to filter the result set''</font>
 
* '''pagesize'''={page size} - limits how many results to return per call. '''Default''': 1000. '''Max''': 50,000.
 
* '''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.
 
* '''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.
 
* '''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:00Z.} - filter by date range. If provided by itself, BioPortal assumes the range should end with the current date and time.
+
* '''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:00Z.} - filter by date range. Optional, can be used with ''createdstartdate'' to limit results to a particular range.
+
* '''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:00Z.} - filter by date range. If provided by itself, BioPortal assumes the range should end with the current date and time.
+
* '''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:00Z.} - filter by date range. Optional, can be used with ''updatedstartdate'' to limit results to a particular range.
+
* '''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.
 
* '''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 ==
 
== Create a provisional term ==
−
* '''Description''': Get all available provisional terms using a paged interface.
+
* '''Description''': Create a provisional term.  
−
* '''Signature (HTTP POST)''': /provisional
+
* '''Signature (HTTP POST)''': ./provisional?apikey={YourAPIKey}
 
* '''Parameters''' (* required)
 
* '''Parameters''' (* required)
 
** * '''preferredname'''={preferred name/label}
 
** * '''preferredname'''={preferred name/label}
−
** * '''ontologyids'''={ontology virtual id(s)} - ontologies that might be interested in implementing the proposed term.
+
** * '''definition'''={definition} - definition for the provisional 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.
 
** * '''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.
+
** '''ontologyids'''={ontology virtual id(s)} - ontologies that might be interested in implementing the provisional term.
 +
** '''synonyms'''={synonyms} - comma-separated list of synonyms for the provisional term
 +
** '''superclass'''={URI for term} - the proposed parent class for the provisional term.
  
 
== Update an existing provisional term ==
 
== Update an existing provisional term ==
−
* '''Description''': Get all available provisional terms using a paged interface.
+
* '''Description''': Update fields for a provisional term.
−
* '''Signature (HTTP PUT)''': /provisional
+
* '''Signature (HTTP PUT)''': ./provisional?apikey={YourAPIKey}
 
* '''Parameters''' (* required)
 
* '''Parameters''' (* required)
 
** * '''termid'''={URI for term}
 
** * '''termid'''={URI for term}
Line 49: Line 57:
  
 
== Delete an existing provisional term ==
 
== Delete an existing provisional term ==
−
* '''Description''': Get all available provisional terms using a paged interface.
+
* '''Description''': Delete a provisional term.
−
* '''Signature (HTTP DELETE)''': /provisional
+
* '''Signature (HTTP DELETE)''': ./provisional?apikey={YourAPIKey}
 
* '''Parameters''' (* required)
 
* '''Parameters''' (* required)
 
** * '''termid'''={URI for term}
 
** * '''termid'''={URI for term}

Latest revision as of 13:09, 9 July 2012

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

Get all provisional terms

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}
    • * definition={definition} - definition for the provisional 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.
    • ontologyids={ontology virtual id(s)} - ontologies that might be interested in implementing the provisional term.
    • synonyms={synonyms} - comma-separated list of synonyms for the provisional term
    • superclass={URI for term} - the proposed parent class for the provisional term.

Update an existing provisional term

  • Description: Update fields for a provisional term.
  • 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: Delete a provisional term.
  • Signature (HTTP DELETE): ./provisional?apikey={YourAPIKey}
  • Parameters (* required)
    • * termid={URI for term}
Retrieved from "https://www.bioontology.org//mediawiki/index.php?title=BioPortal_Provisional_Terms&oldid=12378"