82
edits
IDigBio API v1 Specification: Difference between revisions
Jump to navigation
Jump to search
no edit summary
(add error code section) |
No edit summary |
||
| (21 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]]. | 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 32: | Line 34: | ||
*Media - A media endpoint returns one or more HTTP redirects to an actual media file (typically a JPEG image). | *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". | |||
For example, a Recordset record may include links to its publisher, the related records, and the related mediarecords. | |||
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 items. If the number of related items for a particular type is less than 20, the items will simply be included in the idigbio:links section. | |||
[[iDigBio API Examples]] includes examples that demonstrate this behavior. | |||
[[#toc|Back to contents]] | [[#toc|Back to contents]] | ||
| Line 310: | Line 321: | ||
|- | |- | ||
|quality | |quality | ||
|"thumbnail" "webview" | |"thumbnail" "webview" "fullsize" | ||
| | |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 553: | Line 564: | ||
|- | |- | ||
|quality | |quality | ||
|"thumbnail" "webview" | |"thumbnail" "webview" "fullsize" | ||
| | |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 1,139: | 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,170: | Line 1,184: | ||
<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,179: | 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,256: | 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: | ||