iDigBio

IDigBio API: Difference between revisions

Page Discussion

IDigBio API (view source)

Revision as of 18:37, 13 April 2016

952 bytes added ,  13 April 2016
no edit summary
No edit summary
(15 intermediate revisions by 4 users not shown)
Line 5: Line 5:
== iDigBio API Overview ==
== iDigBio API Overview ==


Please join our list at '''idigbio-api-users-l@lists.ufl.edu''' if you are using our API so we can notify you of changes. You can join via the web at: http://lists.ufl.edu/cgi-bin/wa?A0=IDIGBIO-API-USERS-L
This document serves as the starting page of official documentation for the iDigBio Application Programming Interface (API).
This document serves as the starting page of official documentation for the iDigBio Application Programming Interface (API).


Line 13: Line 12:


The iDigBio API is an abstraction layer for retrieving data from the iDigBio back-end data systems. This abstraction allows reuse and mashup of aggregated data without needing to understand the complex underlying details of the back-end data storage. Currently, the public API supports HTTP GET and POST requests for data read operations only. The iDigBio API is a RESTful web service that delivers data primarily as JSON documents.
The iDigBio API is an abstraction layer for retrieving data from the iDigBio back-end data systems. This abstraction allows reuse and mashup of aggregated data without needing to understand the complex underlying details of the back-end data storage. Currently, the public API supports HTTP GET and POST requests for data read operations only. The iDigBio API is a RESTful web service that delivers data primarily as JSON documents.
== iDigBio API Mailing List ==
Please join our list at '''idigbio-api-users-l@lists.ufl.edu''' if you are using our APIs. Besides providing notification of API changes, the mailing list gives direct access to the iDigBio API developers and is a good place to ask questions or give and receive feedback.
You can join via the web at: http://lists.ufl.edu/cgi-bin/wa?A0=IDIGBIO-API-USERS-L


== Specification ==
== Specification ==


iDigBio is transitioning from version 1 to version 2 (v1 to v2) of the API. We plan to keep the v1 endpoints in production for the foreseeable future. However, most programmers who are interested in accessing data directly in iDigBio via an API are going to be interested in the new v2 features. '''The v2 API is also known as the iDigBio Search API.'''
The [https://github.com/idigbio/idigbio-search-api/wiki iDigBio API v2 / iDigBio Search API specification] includes detailed information about the Search API endpoints, parameters, query format, values, and returns. It is available in the github wiki associated with the [https://github.com/iDigBio/idigbio-search-api code repository]. The iDigBio Search API was released to production in June 2015.


The [https://github.com/idigbio/idigbio-search-api/wiki iDigBio API v2 / iDigBio Search API specification] includes detailed information about the Search API endpoints, parameters, query format, values, and returns. It is available in the github wiki associated with the [https://github.com/iDigBio/idigbio-search-api code repository]. The iDigBio Search API is currently in beta with a target release to production by June 2015.
iDigBio transitioned from version 1 to version 2 (v1 to v2) of the API. All v1 endpoints and documentation should be considered deprecated, even if they continue to function. Programmers who are interested in accessing data directly in iDigBio via an API should consult the v2 API documentation. '''The v2 API is also known as the iDigBio Search API.'''


The [[iDigBio API v1 Specification]] includes detailed information about the v1 API endpoints, parameters, values, and returns. In most cases, the only reason to use the v1 API is to retrieve raw, unprocessed versions of a record (e.g. no iDigBio data quality enhancements) or to access previous versions of a particular record.
The now-deprecated [[iDigBio API v1 Specification]] includes detailed information about the old v1 API endpoints, parameters, values, and returns. In most cases, the only reason to use the v1 API was to retrieve raw, unprocessed versions of a record (e.g. no iDigBio data quality enhancements) or to access previous versions of a particular record.


== Examples ==
== Examples ==


See [https://github.com/iDigBio/idigbio-search-api/wiki/Examples iDigBio API v2 / iDigBio Search API Examples] in the [https://github.com/iDigBio/idigbio-search-api/wiki idigbio-search-api github wiki].
See [https://github.com/iDigBio/idigbio-search-api/wiki/Examples iDigBio API v2 / iDigBio Search API Examples] in the [https://github.com/iDigBio/idigbio-search-api/wiki idigbio-search-api github wiki].
 
See [[IDigBio API v1 Examples]] for examples of the iDigBio v1 API in action.


== Quick Start ==
== Quick Start ==
Line 32: Line 35:
iDigBio API endpoints follow the general form:
iDigBio API endpoints follow the general form:


;<pre>http://api.idigbio.org/{api_version}{endpoint}{optional_parameters}</pre>
;<pre>https://search.idigbio.org/{api_version}/{endpoint}{optional_parameters}</pre>


In nearly all cases, a successful API request returns data as a JSON-formatted document.
In nearly all cases, a successful API request returns data as a JSON-formatted document.


Many error cases will also return a JSON-formatted document rather than a bare HTTP status failure.
Many error cases will also return a JSON-formatted document rather than a bare HTTP status failure.


== Searching iDigBio ==
== Searching iDigBio ==
Line 47: Line 49:
=== Search API ===
=== Search API ===


The [https://github.com/idigbio/idigbio-search-api/wiki iDigBio Search API] is currently in beta testing. The next release of the iDigBio Portal will make use of this v2 API and the new search features provided.
The [https://github.com/idigbio/idigbio-search-api/wiki iDigBio Search API] has be released and the June 2015 version of the portal is based on this API.


=== Other APIs ===
=== Other APIs ===
[[iDigBio Download API]]
[[iDigBio Download API]]
[[https://docs.google.com/document/d/1C75oUWk7Wbbo81-ldh-ogOurNjbIQ-ZLPqSQVR-hc5A/edit?usp=sharing Media API Working Docs]]
 
[https://docs.google.com/document/d/1C75oUWk7Wbbo81-ldh-ogOurNjbIQ-ZLPqSQVR-hc5A/edit?usp=sharing Media API Working Docs]
 
=== Specimen Web Map Module ===
 
The iDigBio Portal Search page map is also provided as a stand-alone module for use in any third-party web site. Go to the [[Specimen Map]] page for details on using the map.


=== Elasticsearch Overview ===
=== Elasticsearch Overview ===
Line 58: Line 65:


The public-facing interface to the iDigBio back-end Elasticsearch system is deprecated and will likely be disabled at some point in the future.
The public-facing interface to the iDigBio back-end Elasticsearch system is deprecated and will likely be disabled at some point in the future.
== Full Recordset Downloads ==
Instead of generating large queries in the portal or with the API, it may be easier to download iDigBio data from regular dumps of all data in iDigBio. These dumps are available from [http://s.idigbio.org/idigbio-static-downloads?max-keys=10000 s.idigbio.org]. This is an S3-compatible object store (although it can be treated as a web server if that is easier) that contains .zip files of each record set in iDigBio named by recordset uuid as well as files containing all data across all records sets.


== Client Libraries ==
== Client Libraries ==
Line 67: Line 78:
R is a free software environment for statistical computing and graphics. It compiles and runs on a wide variety of UNIX platforms, Windows and MacOS.
R is a free software environment for statistical computing and graphics. It compiles and runs on a wide variety of UNIX platforms, Windows and MacOS.


R Package Coming soon! Draft available at https://github.com/idigbio/ridigbio
The production version of this package is in [http://cran.r-project.org/web/packages/ridigbio/index.html CRAN]. The latest development version is available at https://github.com/idigbio/ridigbio


The ridigbio R package is an "official" client library in the iDigBio code repository.
The ridigbio R package is an "official" client library in the iDigBio code repository.
Line 103: Line 114:
== Suggestions? ==
== Suggestions? ==


If you are in need of other client libraries or iDigBio API features, please use the feedback button to submit your request.
If you are in need of other client libraries or iDigBio API features, please use the [https://www.idigbio.org/modal_forms/nojs/contact feedback button] to submit your request.
Grungle
946

edits

Retrieved from "http://www.idigbio.org/wiki/index.php/Special:MobileDiff/15812...20560"