View source for IDigBio Download API

[[Category:CYWG]]
[[Category:API]]
[[Category:Documentation]]

== Overview ==

The Download API works by performing the requested query and building a Darwin Core Archive. Once archive generation has begun, the status endpoint can be polled to determine if the generation has been completed. Once the archive generation is completed, the API provides a link to the file for download. If the optional email parameter is supplied on the query request, an email notification will be sent that includes a link to the downloadable file.

Large queries (and thus large archive file creation) can take multiple hours to complete.

;;GET requests

A query submitted as a GET request must be URL-encoded.

;;POST requests

<s>A query submitted as a POST request must be supplied as JSON in the content body and specify the "Content-Type: application/json" request header.</s>

Documentation for POST requests coming in the future. Please contact us if you have a need for this documentation.

== Query Endpoint ==

The download service query url:

<pre>
https://api.idigbio.org/v2/download/?rq={Query in iDigBio query format}[&email={valid email address}]
</pre>

See [https://github.com/iDigBio/idigbio-search-api/wiki/Query-Format iDigBio query format] for more information on writing queries.

The "email" parameter is optional. Specifying a valid email address will cause an email notification to be sent.

A successful request to the query endpoint will return a JSON document that includes a "complete" status flag and a "status_url" link. The "status_url" is a link to the Status Endpoint (see below) which can safely be polled until "complete" is "true".


== Status Endpoint ==

The download service status url:

<pre>
http://api.idigbio.org/v2/download/{status uuid}
</pre>

Using the "status_url" that was returned in the JSON from the query endpoint, a successful request to the status endpoint will return a JSON document that includes a number of fields including "complete" which is a status flag and "download_url" which, once the generation is completed, is a link to the generated archive.

=== Query Example - genus acer with email ===

Consider the following query:

<pre>
{ "genus" : "acer"}
</pre>

We could request a download and notification sent to email address "donotreply@idigbio.org" via the following url:

<pre>
https://api.idigbio.org/v2/download/?rq=%7B%22genus%22%3A%22acer%22%7D&email=donotreply%40idigbio.org
</pre>

After the downloadable archive file is generated, the "complete" field will be set to "true" and the "download_url" field will include a link to the available file.

Using curl (output formatted with JSON "prettify"), we can see that a completed archive is available at the download_url:

<pre>
$ curl "https://api.idigbio.org/v2/download/?rq=%7B%22genus%22%3A%22acer%22%7D"
{
  "complete": false, 
  "core_source": "indexterms", 
  "core_type": "records", 
  "expires": "2015-07-21T14:17:19.715995", 
  "form": "dwca-csv", 
  "mediarecord_fields": null, 
  "mq": null, 
  "record_fields": null, 
  "rq": {
    "genus": "acer"
  }, 
  "status_url": "https://localhost:30000/v2/download/fd8de83e-7fb7-4edd-8a6a-f11234eec664", 
  "task_status": "PENDING"
}
</pre>

which is the same link that would be included in the "iDigBio Download Ready" email.

If we follow the "status_url" in the above we see similar information:

<pre>
$ curl -s "https://api.idigbio.org/v2/download/fd8de83e-7fb7-4edd-8a6a-f11234eec664"
{
  "complete": false, 
  "core_source": "indexterms", 
  "core_type": "records", 
  "expires": "2015-07-21T14:17:19.715995", 
  "form": "dwca-csv", 
  "mediarecord_fields": null, 
  "mq": null, 
  "record_fields": null, 
  "rq": {
    "genus": "acer"
  }, 
  "status_url": "https://localhost:30000/v2/download/fd8de83e-7fb7-4edd-8a6a-f11234eec664", 
  "task_status": "PENDING"
}
</pre>

=== Status Endpoint Example ===

Given the following query JSON:

<pre>
{ "genus" : "acer" }
</pre>

becomes the following when url-encoded:

<pre>
https://api.idigbio.org/v2/download/?rq=%7B%22genus%22%3A%22acer%22%7D
</pre>

Immediately after the query is run, the "complete" flag is still set to false. There is no archive available for download (yet).

<pre>
{
  "complete": false, 
  "core_source": "indexterms", 
  "core_type": "records", 
  "expires": "2015-07-21T14:17:19.715995", 
  "form": "dwca-csv", 
  "mediarecord_fields": null, 
  "mq": null, 
  "record_fields": null, 
  "rq": {
    "genus": "acer"
  }, 
  "status_url": "https://localhost:30000/v2/download/fd8de83e-7fb7-4edd-8a6a-f11234eec664", 
  "task_status": "PENDING"
}
</pre>

If we wait a while and try again, the status changes, and the file is available at the provided download_url:

<pre>
{
  "complete": true, 
  "core_source": "indexterms", 
  "core_type": "records", 
  "expires": "2015-07-21T14:17:19.715995", 
  "form": "dwca-csv", 
  "mediarecord_fields": null, 
  "mq": null, 
  "record_fields": null, 
  "rq": {
    "genus": "acer"
  }, 
  "status_url": "https://localhost:30000/v2/download/fd8de83e-7fb7-4edd-8a6a-f11234eec664", 
  "task_status": "SUCCESS"
}
</pre>