IDigBio API

From iDigBio
Revision as of 16:10, 18 November 2013 by Gtraub (talk | contribs)
Jump to navigation Jump to search

API Basics


The iDigBio API is a RESTful pattern HTTP API that primarily delivers data in JSON format. Currently the API supports GET requests or data read operations only.

API URLs have several parameters in them, and typically follow the form of 

<base url>/<version>/<type>/<id>

For example: 

 Using the following parameters for an API request

 base url = http://api.idigbio.org
 version = v1
 type = records
 id = 00000230-01bc-4a4f-8389-204f39da9530

 would produce a URL of the following form

 "http://api.idigbio.org/v1/records/00000230-01bc-4a4f-8389-204f39da9530"


There are two major types of API enpoints:

  • Collection - which is a group endpoint that returns lists of multiple records. These urls are of the form <base url>/<version>/<type>, such as http://api.idigbio.org/v1/mediarecords/ . Additionally, a collection endpoint can contain optional query parameters, [?limit] indicates the number of records returned in the collection and defaults to 1000 and the [?offset] parameter which indicates the number of records to skip before returning a set of records and defaults to 0. If a collection endpoint request finds more then the set limit of records it will include a "next page" link to retrieve the next set of records in the collection. See the endpoint properties section for more information on properties returned.
  • Entity - A single item endpoint which returns all of the data available about an object. These urls are of the form <base url>/<version>/<type>/<id> like the example used above.

Examples: 

collection:
"http://api.idigbio.org/v1/mediarecords"
collection w/ optional query parameters:
"http://api.idigbio.org/v1/mediarecords?limit=100&offset=100"
entity:
"http://api.idigbio.org/v1/mediarecords/00000230-01bc-4a4f-8389-204f39da9530"


Endpoint Basics


Calling just the base URL will return a list of API version endpoints. For example a GET request to "http://api.idigbio.org" will return JSON data like the example below. 

{
v1: "http://api.idigbio.org/v1/",
v0: "http://api.idigbio.org/v0/"
}

and calling a version URL endpoint will return a list of major data types available for that version, such as: 

{
recordsets: "http://api.idigbio.org/v1/recordsets",
records: "http://api.idigbio.org/v1/records",
mediarecords: "http://api.idigbio.org/v1/mediarecords",
mediaaps: "http://api.idigbio.org/v1/mediaaps",
people: "http://api.idigbio.org/v1/people",
organizations: "http://api.idigbio.org/v1/organizations",
taxa: "http://api.idigbio.org/v1/taxa",
aggregates: "http://api.idigbio.org/v1/aggregates"
}


Endpoint Properties


The iDigBio API tries to follow the REST paradigm's HATEOAS (Hypermedia as the Engine of Application State) model, which basically means that within each API endpoint we provide a list of relevant links to further API actions. This list typically is stored in either the "idigbio:links" in v1 or below or the "links" property in v3. In general, the largest difference between v1 and v3 responses is that the "idigbio:" namespace has been dropped from all system-level property names.

Other system level property names include

For Entity Endpoints:

  • etag - the opaque identifier assigned to a specific version of a resource found at a URL
  • dateModified - The date the entity was modified
  • version - The entity's version number
  • type - The entity's type
  • uuid - The entity's uuid
  • siblings - Any siblings the entity may have as a dictionary of uuids
  • recordIds - A list of lookup keys for the entity
  • data - The entity's encapsulated data element

For Collection Endpoints:

  • items - the list of items in the collection
  • itemCount - the number of total items in the collection

The data element for each entity can include any number of key-value pairs containing properties of the entity, including potentially values that are themselves lists or dictionaries. Typical key namespaces that might appear in each type are (in order of decreasing usefulness):

  • Records: typically contains darwin core elements ( http://rs.tdwg.org/dwc/terms/index.htm ) describing a physical specimen, may also contain custom elements or elements defined by other standards.
  • MediaRecords: typically contains audubon core elements ( http://terms.gbif.org/wiki/Audubon_Core_Term_List_(1.0_normative) ) describing a media capture event, may also contain custom elements or elements defined by other standards.
  • MediaAPs: defined internally, contains references to the location of binary media objects within our object stores.
  • RecordSets: currently undefined, in v3 will have a fixed format derived from our collection registration parameters.
  • DataFiles: defined internally, contains references to the location of binary data file objects within our object stores.
  • People: defined internally, contains records of people who have interacted with the iDigBio system, such as data provider contacts, users of the system, or other related people.
  • Organizations: defined internally, contains records of organizations who interact with iDigBio. Right now this primarily contains the data from our collection registrations.
  • Taxa: currently undefined and unused. May eventually hold taxonomic records, most likely following the darwin core standard.
  • Aggregates: currently undefined and unused. May eventual hold incrementally built lists of records, such as the cached results of search queries or manually curated record groups.


Available API endpoints


All endpoints follow the form of "http://api.idigbio.org/{api_version}{endpoint}"

Endpoint Method API Versions Available Description
'/mediarecords' GET v0, v1 returns a collection of media record UUIDs
'/mediarecords/{UUID}' GET v0, v1 returns a media record with the specific entity UUID
'/mediaaps' GET v0, v1 returns a collection of media access point UUIDs
'/mediaaps/{UUID}' GET v0, v1 returns the media with the specific entity UUID
'/organizations' GET v1 returns a collection of organizations UUIDs
'/organizations/{UUID}' GET v1 returns a organization record with the specific entity UUID
'/people' GET v1 returns a collection of people UUIDs
'/people/{UUID}' GET v1 returns a person record with the specific entity UUID
'/records' GET v0, v1 returns a collection of record UUIDs
'/records/{UUID}' GET v0, v1 returns a record with the specific entity UUID
'/recordsets' GET v0, v1 returns a collection of record set UUIDs
'/recordsets/{UUID}' GET v0, v1 returns a record set with specific entity UUID
Retrieved from "http://www.idigbio.org/wiki/index.php?title=IDigBio_API&oldid=6280"