IDigBio API v1 Specification: Difference between revisions

Jump to navigation Jump to search
no edit summary
(add query terms for mediarecords →‎Search)
No edit summary
 
(41 intermediate revisions by 2 users not shown)
Line 2: Line 2:
[[Category:API]]
[[Category:API]]
[[Category:Documentation]]
[[Category:Documentation]]
{{Caution|The v1 API has been superseded by [https://github.com/idigbio/idigbio-search-api/wiki iDigBio API v2 / iDigBio Search API]. API users should migrate to using the most recent version of the API. This page remains for historical reference.}}


== API Version Information ==
== API Version Information ==


This is the specification for v1 of the [[iDigBio API]]. Previous versions of the API continue to exist but should be considered deprecated. API users should migrate to using the current version of the API. This document supercedes [[iDigBio API v0 Specification]].
This is the specification for v1 of the [[iDigBio API]]. The v1 API has been superceded by [https://github.com/idigbio/idigbio-search-api/wiki iDigBio API v2 / iDigBio Search API]. API users should migrate to using the most recent version of the API. The v1 API specification supercedes [[iDigBio API v0 Specification]]. Previous versions of the API may continue to exist but should be considered deprecated.


== iDigBio Data and Schema ==
== iDigBio Data and Schema ==
Line 18: Line 20:
== Endpoints ==
== Endpoints ==


Unless otherwise noted, successful responses from the API will return a JSON-formatted document.
'''Unless otherwise noted, a successful response from an API endpoint will return a JSON-formatted document.'''
 
The curly braces <code> { </code> and <code> } </code> in this document are used as a placeholder to indicate that a real value needs to be substituted.  For example, <code> {api_version} </code> would be replaced with the actual representation of the API version such as "v1" (without the quotes).


Most of the provided examples include a JSON formatter (such as json_pp) to make the output easier for humans to read. Additional usage examples as well as information on JSON formatting and the "curl" command, are available in [[iDigBio API Examples]].
Most of the provided usage examples include a JSON formatter (such as json_pp) to make the JSON document response easier for humans to read. Additional usage examples as well as information on JSON formatting and the "curl" command, are available in [[iDigBio API Examples]].


There are two major types of API enpoints:  
There are three major types of API endpoints:  


*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 [[#endpointprops|endpoint properties]] section for more information on properties returned.
*List - The endpoint returns a JSON document containing a list of iDigBio UUIDs and links to other records. The List of UUIDs normally does not contain content data. To get to record content data, links to each item in the List are followed.
   
   
*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.
*Full Record - The endpoint returns a JSON document representing a Full Record for a type of object.  Examples include a Specimen Record or a Media Record. The Full Record endpoint is used to retrieve all of the data about a particular object.
 
*Media - A media endpoint returns one or more HTTP redirects to an actual media file (typically a JPEG image).
 
'''Special Note about the idigbio:links section'''
 
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 a list of relevant links to further API actions is included. The list of relevant links to further API actions is typically stored in "idigbio:links".


Examples:
For example, a Recordset record may include links to its publisher, the related records, and the related mediarecords.


collection:
If the number of related items for a particular type exceeds 20, the idigbio:links for that type of relation will be a single link to a List of itemsIf the number of related items for a particular type is less than 20, the items will simply be included in the idigbio:links section.
"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"


[[iDigBio API Examples]] includes examples that demonstrate this behavior.


[[#toc|Back to contents]]
[[#toc|Back to contents]]
Line 44: Line 50:


;Description
;Description
:Returns a list of top-level api_version or service URLs
:Returns a List of top-level API versions or service URLs.


;Resource URL
;Resource URL
Line 71: Line 77:


;Description
;Description
:Returns a list of top-level API feature types for a particular version of the API
:Returns a List of top-level API feature types for a particular version of the API.


;Resource URL
;Resource URL
Line 120: Line 126:


;Description
;Description
:Returns a collection (list) of Media Record entities.
:Returns a List of Media Record iDigBio UUIDs. The iDigBio UUID is represented by the "idigbio:uuid" data field.


;Resource URL
;Resource URL
Line 137: Line 143:
|limit
|limit
|0, 1, 2, 10, ..., 100, ..., 1000, ..., n
|0, 1, 2, 10, ..., 100, ..., 1000, ..., n
|Controls the number of entities returned by a collection url. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000.
|Controls the number of items returned in the List. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000.
|-
|-
|offset
|offset
|0, 1, 2, ... 1000, ..., 10000, ..., n
|0, 1, 2, ... 1000, ..., 10000, ..., n
|Controls the starting entity offset for paging through the API. Large offsets, greater than 1000000 (1 million) are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.
|Controls the starting offset for paging through the API. Large offsets, greater than 1000000 (1 million) are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.
|}
|}


;Sample Usage
;Sample Usage


Request 5 media record entities:
Request five media record items:


<pre>
<pre>
Line 226: Line 232:


;Description
;Description
:Returns the full Media Record matching the specified iDigBio UUID. A Media Record contains metadata about an image.
:Returns the full Media Record matching the specified iDigBio UUID. The iDigBio UUID is represented by the "idigbio:uuid" data field. A Media Record contains metadata and relationship information about media (typically an image).


;Resource URL
;Resource URL
Line 299: Line 305:


;Description
;Description
:Returns an image file (JPEG) or (one or more) HTTP Redirects to an image file that is associated with the specified iDigBio UUID. Omitting the "quality" parameter will return the full size image specified in the source data accessURI field and is usually served from the provider's infrastructure. Specifying the "quality" parameter will return a derivative image file that is hosted on iDigBio infrastructure. For many use cases, the recommended use of this endpoint would include the quality parameter.
:Returns one or more HTTP redirects to a target image file (JPEG) that is associated with the specified iDigBio UUID. Omitting the "quality" parameter will return the full size image specified in the source data accessURI field and is usually served from the provider's infrastructure. Specifying the "quality" parameter will return a derivative image file that is hosted on iDigBio infrastructure. For many use cases, the recommended use of this endpoint would include the quality parameter.


;Resource URL
;Resource URL
Line 315: Line 321:
|-
|-
|quality
|quality
|"thumbnail" "webview"
|"thumbnail" "webview" "fullsize"
|Specifiy the quality of the image returned from the API. Omitting quality will return the full-size original image. The values "thumbnail" and "webview" return derivative images of width 260 and 600 pixels respectively.
|Specify the quality of the JPEG image returned from the API. The values "thumbnail" or "webview" return derivative images of width 260 and 600 pixels respectively. The value "fullsize" returns a derivative image that matches the size (width in pixels) of the original image. Omitting quality will return the full-size original image as specified in accessURI by the provider.
|}
|}


Line 340: Line 346:


;Description
;Description
:Returns a collection (list) of Specimen Record entities
:Returns a List of Specimen Record iDigBio UUIDs. The iDigBio UUID is represented by the "idigbio:uuid" data field.


;Resource URL
;Resource URL
Line 357: Line 363:
|limit
|limit
|0, 1, 2, 10, ..., 100, ..., 1000, ..., n
|0, 1, 2, 10, ..., 100, ..., 1000, ..., n
|Controls the number of entities returned by a collection url. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000.   
|Controls the number of items returned. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000.   
|-
|-
|offset
|offset
|0, 1, 2, ... 1000, ..., 10000, ..., n
|0, 1, 2, ... 1000, ..., 10000, ..., n
|Controls the starting entity offset for paging through the API. Large offsets, greater than 1000000 (1 million) are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.  
|Controls the starting offset for paging through the API. Large offsets, greater than 1000000 (1 million) are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.  
|}
|}


;Sample Usage
;Sample Usage


Request 5 specimen record entity ids:
Request five specimen record items:


<pre>
<pre>
Line 447: Line 453:


;Description
;Description
:Returns a Specimen Record matching the specific iDigBio UUID. The iDigBio UUID is represented by the "idigbio:uuid" data field.
:Returns a full Specimen Record matching the specified iDigBio UUID. The iDigBio UUID is represented by the "idigbio:uuid" data field. A Specimen Record contains occurrence data.




Line 542: Line 548:


;Description
;Description
:Returns an image file (JPEG) associated with the specific iDigBio UUID (via the relationship to a mediarecord). If multiple mediarecords are associated with a specimen record, the particular image returned in non-deterministic.
:Returns one or more HTTP redirects to a target image file (JPEG) that is associated with the specified iDigBio UUID (via the relationship to a mediarecord). If multiple mediarecords are associated with a specimen record, the particular mediarecord chosen by the API is non-deterministic.  Omitting the "quality" parameter will return the full size image specified in the source data accessURI field and is usually served from the provider's infrastructure. Specifying the "quality" parameter will return a derivative image file that is hosted on iDigBio infrastructure. For many use cases, the recommended use of this endpoint would include the quality parameter. .


;Resource URL
;Resource URL
Line 558: Line 564:
|-
|-
|quality
|quality
|"thumbnail" "webview"
|"thumbnail" "webview" "fullsize"
|Specifiy the quality of the image returned from the API. Omitting quality will return the full-size high quality original image from source provider. The values "thumbnail" and "webview" return images of width 260 and 600 pixels respectively.
|Specify the quality of the JPEG image returned from the API. The values "thumbnail" or "webview" return derivative images of width 260 and 600 pixels respectively. The value "fullsize" returns a derivative image that matches the size (width in pixels) of the original image. Omitting quality will return the full-size original image as specified in accessURI by the provider.
|}
|}


Line 579: Line 585:
[[#toc|Back to contents]]
[[#toc|Back to contents]]
----
----


=== GET /v1/organizations ===
=== GET /v1/organizations ===
Line 600: Line 605:


;Description
;Description
:Returns a collection (list) of publisher entities.
:Returns a List of Publisher iDigBio UUIDs. Publishers are the top-level entities containing metadata about data publishing locations.


;Resource URL
;Resource URL
Line 618: Line 623:
|limit
|limit
|0, 1, 2, ..., 10, ..., n
|0, 1, 2, ..., 10, ..., n
|Controls the number of entities returned.
|Controls the number of items returned.
|-
|-
|offset
|offset
|0, 1, 2, ..., 10, ..., n
|0, 1, 2, ..., 10, ..., n
|Controls the starting entity offset for paging through the API.
|Controls the starting offset for paging through the API.
|}
|}


;Sample Usage
;Sample Usage


Retrieve a list with only one publisher entity.
Retrieve a List with only one publisher entity.


<pre>
<pre>
Line 668: Line 673:


;Description
;Description
:Returns a full Publisher record that matches the specified iDigBio UUID. A publisher record includes links to all of the recordsets provided to iDigBio by the publisher as well as other information.
:Returns a full Publisher Record matching the specified iDigBio UUID. A publisher record includes links to all of the recordsets provided to iDigBio by the publisher as well as other information about each recordset.


;Resource URL
;Resource URL
Line 781: Line 786:
       }
       }
   }
   }
}
</pre>
[[#toc|Back to contents]]
----
=== GET /v1/publishers/{UUID}/recordsets ===
;Description
:Return a List of recordset iDigBio UUIDs that are associated with the Publisher of the specified iDigBio UUID (returns a list of recordsets that are published by a particular Publisher).
;Resource URL
<pre>
http://api.idigbio.org/v1/publishers/{UUID}/recordsets
</pre>
;Optional Parameters
{| class="wikitable" style="background-color: #ffffcc;" width="100%"
!parameter
!valid values
!detailed description
|-
|limit
|0, 1, 2, ..., 10, ..., n
|Controls the number of items returned.
|-
|offset
|0, 1, 2, ..., 10, ..., n
|Controls the starting offset for paging through the API.
|}
;Sample Usage
<pre>
$ curl -s http://api.idigbio.org/v1/publishers/d347ee15-f16e-4650-930c-4e54d9ce549e/recordsets | json_pp
{
  "idigbio:errors" : [],
  "idigbio:links" : {},
  "idigbio:items" : [
      {
        "idigbio:links" : {
            "recordset" : "http://api.idigbio.org/v1/recordsets/271a9ce9-c6d3-4b63-a722-cb0adc48863f"
        },
        "idigbio:uuid" : "271a9ce9-c6d3-4b63-a722-cb0adc48863f"
      }
  ],
  "idigbio:itemCount" : "1"
}
}


Line 791: Line 847:


;Description
;Description
:Returns a list of recordset entities.
:Returns a List of recordset iDigBio UUIDs. A recordset is a group of published data.


;Resource URL
;Resource URL
Line 808: Line 864:
|limit
|limit
|0, 1, 2, ..., 10, ..., n
|0, 1, 2, ..., 10, ..., n
|Controls the number of entities returned.
|Controls the number of items returned.
|-
|-
|offset
|offset
|0, 1, 2, ..., 10, ..., n
|0, 1, 2, ..., 10, ..., n
|Controls the starting entity offset for paging through the API.
|Controls the starting offset for paging through the API.
|}
|}


;Sample Usage
;Sample Usage


Request 3 recordset entities:
Request a List of recordset iDigBio UUIDs (and in this usage example, limit the number of results to 3):


<pre>
<pre>
Line 876: Line 932:


;Description
;Description
:Returns the full record about a recordset with the specified iDigBio UUID
:Returns the full Recordset record with the specified iDigBio UUID.


;Resource URL
;Resource URL
Line 955: Line 1,011:


;Description
;Description
:Returns a list of mediarecord IDs that belong to the particular recordset of the specified iDigBio UUID
:Returns a List of Media Record iDigBio UUIDs that belong to the recordset of the specified iDigBio UUID.


;Resource URL
;Resource URL
Line 972: Line 1,028:
|limit
|limit
|0, 1, 2, 10, ..., 100, ..., 1000, ..., n
|0, 1, 2, 10, ..., 100, ..., 1000, ..., n
|Controls the number of entities returned by a collection url. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000.
|Controls the number of items returned. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000.
|-
|-
|offset
|offset
|0, 1, 2, ... 100, ..., 1000, ..., n
|0, 1, 2, ... 100, ..., 1000, ..., n
|Controls the starting entity offset for paging through the API. Large offsets, greater than 1000000 (1 million) are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.
|Controls the starting offset for paging through the API. Large offsets, greater than 1000000 (1 million) are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.
|}
|}


;Sample Usage
;Sample Usage


Return a list with a single mediarecord that belongs to a particular recordset.
Return a List of mediarecord iDigBio UUIDs that belong to a particular recordset (and in this usage example, limit the number of results to 1):


<pre>
<pre>
Line 1,021: Line 1,077:


;Description
;Description
:Returns a list of record IDs that belong to the recordset of the specified entity ID
:Returns a List of iDigBio UUIDs that belong to the recordset of the specified entity ID.


;Resource URL
;Resource URL
Line 1,038: Line 1,094:
|limit
|limit
|0, 1, 2, 10, ..., 100, ..., 1000, ..., n
|0, 1, 2, 10, ..., 100, ..., 1000, ..., n
|Controls the number of entities returned by a collection url. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000.   
|Controls the number of items returned. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000.   
|-
|-
|offset
|offset
|0, 1, 2, ... 1000, ..., 10000, ..., n
|0, 1, 2, ... 1000, ..., 10000, ..., n
|Controls the starting entity offset for paging through the API. Large offsets, greater than 1000000 (1 million) are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.  
|Controls the starting offset for paging through the API. Large offsets, greater than 1000000 (1 million) are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.  
|}
|}


Line 1,094: Line 1,150:


== Search ==
== Search ==
{{Caution|'''Direct queries to the iDigBio Elasticsearch service are deprecated. The [https://github.com/idigbio/idigbio-search-api/wiki iDigBio API v2 / iDigBio Search API specification] should be used instead.'''
The public-facing interface to the iDigBio back-end Elasticsearch system will likely be disabled at some point in the future.}}


Elasticsearch is an open source distributed document-oriented NoSQL search system.  Although not technically part of the API, iDigBio exposes a public Elasticsearch interface for programmers to access advanced search functionality of iDigBio data.
Elasticsearch is an open source distributed document-oriented NoSQL search system.  Although not technically part of the API, iDigBio exposes a public Elasticsearch interface for programmers to access advanced search functionality of iDigBio data.
Line 1,122: Line 1,181:
|}
|}


The query string is appended to the URL as a parameter named "q" and in simplest form follows the following pattern:
The query string is appended to the URL as a parameter named "q" and follows the following pattern:


<pre>
<pre>
http://search.idigbio.org/idigbio/records/_search?q=term:value
http://search.idigbio.org/idigbio/records/_search?&q=term:value
</pre>
</pre>
The number of records returned can be adjusted with the "size" parameter.


Search examples that are specific to iDigBio are available in [[iDigBio API Examples]].
Search examples that are specific to iDigBio are available in [[iDigBio API Examples]].
In most cases, iDigBio Elasticsearch terms are generated by dropping the leading namespace and colon, then lowercasing the remaining portion. This was done for a number of reasons including the fact that Elasticsearch itself uses colons in the query syntax.
Some examples:
{| class="wikitable"
!Definition
!DwC Term / iDigBio API Record Field
!iDigBio Elasticsearch Index Term
|-
|Scientific Name
|dwc:scientificName
|scientificname
|-
|Institution Code
|dwc:institutionCode
|institutioncode
|-
|iDigBio Record UUID
|idigbio:uuid
|uuid
|-
|...
|...
|...
|}


[[#toc|Back to contents]]
[[#toc|Back to contents]]
Line 1,134: Line 1,222:


=== Elasticsearch - Records ===
=== Elasticsearch - Records ===
{{Caution|'''Direct queries to the iDigBio Elasticsearch service are deprecated. The [https://github.com/idigbio/idigbio-search-api/wiki iDigBio API v2 / iDigBio Search API specification] should be used instead.'''}}


Specimen Records Query URL:
Specimen Records Query URL:
Line 1,211: Line 1,301:


=== Elasticsearch - Media Records ===
=== Elasticsearch - Media Records ===
{{Caution|'''Direct queries to the iDigBio Elasticsearch service are deprecated. The [https://github.com/idigbio/idigbio-search-api/wiki iDigBio API v2 / iDigBio Search API specification] should be used instead.'''}}


Media Records Query URL:
Media Records Query URL:
Line 1,228: Line 1,321:
[[#toc|Back to contents]]
[[#toc|Back to contents]]
----
----
== Response and Error Codes ==
The API returns standard HTTP status codes. Errors will likely not return a JSON document so your code should handle the [http://en.wikipedia.org/wiki/List_of_HTTP_status_codes raw HTTP status codes].
82

edits

Navigation menu