IDigBio API v1 Specification: Difference between revisions

Jump to navigation Jump to search

IDigBio API v1 Specification (view source)

Revision as of 14:16, 20 May 2014

5,688 bytes added ,  20 May 2014
make identical to mediarecords parameters and add sample →‎GET /v1/records
(make identical to mediarecords parameters and add sample →‎GET /v1/records)
Line 345: Line 345:


;Description
;Description
:Returns a collection of Specimen Record IDs
:Returns a collection (list) of Specimen Record IDs


;Resource URL
;Resource URL
Line 361: Line 361:
|-
|-
|limit
|limit
|
|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.  
|Controls the number of records returned by a collection url. Large values may cause HTTP requests to time out. Recommended values are from 1 to 1000. 
|-
|-
|offset
|offset
|
|0, 1, 2, ... 1000, ..., 10000, ..., n
|Controls the starting entity offset for paging through the API. Large offsets are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.  
|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.  
|}
|}


;Sample Usage
;Sample Usage


Request the first 5 specimen record entity ids:
<pre>
$ curl -s "http://api.idigbio.org/v1/records?limit=5" | json_pp
{
  "idigbio:errors" : [],
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/records?limit=5&offset=5"
  },
  "idigbio:items" : [
      {
        "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/0000012b-9bb8-42f4-ad3b-c958cb22ae45"
        },
        "idigbio:uuid" : "0000012b-9bb8-42f4-ad3b-c958cb22ae45",
        "idigbio:version" : 2,
        "idigbio:etag" : "9d2209ef58ddfef276e4a06cad57d106942516c1",
        "idigbio:dateModified" : "2014-04-21T04:36:29.192Z"
      },
      {
        "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/00000230-01bc-4a4f-8389-204f39da9530"
        },
        "idigbio:uuid" : "00000230-01bc-4a4f-8389-204f39da9530",
        "idigbio:version" : 3,
        "idigbio:etag" : "b9083a241369e3e1c5a81db7d6e396d796a402ee",
        "idigbio:dateModified" : "2014-04-21T12:23:42.181Z"
      },
      {
        "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/00000234-ac13-4e01-a2ae-e9aa95f35693"
        },
        "idigbio:uuid" : "00000234-ac13-4e01-a2ae-e9aa95f35693",
        "idigbio:version" : 3,
        "idigbio:etag" : "ca72b24d3fe3c4685f417849fcec00a21b201467",
        "idigbio:dateModified" : "2014-05-03T08:57:03.106Z"
      },
      {
        "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/00000330-918b-4d62-bf7f-23a1f4f240e5"
        },
        "idigbio:uuid" : "00000330-918b-4d62-bf7f-23a1f4f240e5",
        "idigbio:version" : 4,
        "idigbio:etag" : "5922ca971561608960f96a4b7b30c83234aa7ea8",
        "idigbio:dateModified" : "2014-04-24T08:16:50.204Z"
      },
      {
        "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/00000397-5012-4dda-9b03-52230c7f4bfc"
        },
        "idigbio:uuid" : "00000397-5012-4dda-9b03-52230c7f4bfc",
        "idigbio:version" : 3,
        "idigbio:etag" : "70d7064d6a135b6d3a66c03f82e95ad498a0c047",
        "idigbio:dateModified" : "2014-04-23T04:50:44.684Z"
      }
  ],
  "idigbio:itemCount" : "15324705"
}
</pre>
Of interest here is that <code> "idigbio:itemCount" </code> contains the number of items of this type in the API. In this case, we have 15324705 specimen records total.
The next "page" of records can be requested by adding an "offset" paramenter.
A link that includes the offset to the next page is provided in the results:
<pre>
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/records?limit=5&offset=5"
  },
</pre>
Request the next 5 items starting at offset 5:
<pre>
$ curl -s "http://api.idigbio.org/v1/records?limit=5&offset=5" | json_pp
{
  "idigbio:errors" : [],
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/records?limit=5&offset=10",
      "idigbio:prevPage" : "http://api.idigbio.org/v1/records?limit=5&offset=0"
  },
  "idigbio:items" : [
      {
        "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/0000041c-3527-4feb-a632-7aa4db4de835"
        },
        "idigbio:uuid" : "0000041c-3527-4feb-a632-7aa4db4de835",
        "idigbio:version" : 4,
        "idigbio:etag" : "ce97525e02a7a6dfe2b2aee4071edb63e7f9a909",
        "idigbio:dateModified" : "2014-04-24T03:48:48.706Z"
      },
      {
        "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/00000450-4701-4e57-a83f-b9f112d87ab2"
        },
        "idigbio:uuid" : "00000450-4701-4e57-a83f-b9f112d87ab2",
        "idigbio:version" : 0,
        "idigbio:etag" : "de94b3e150e68ae5be8156fd8b12c5f94c8a6419",
        "idigbio:dateModified" : "2014-05-03T04:39:59.888Z"
      },
      {
        "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/000005e8-b0bb-4693-8de7-b130417ebbf1"
        },
        "idigbio:uuid" : "000005e8-b0bb-4693-8de7-b130417ebbf1",
        "idigbio:version" : 1,
        "idigbio:etag" : "f0276a28d99a85231014a40b4c9f1accc9e80b6a",
        "idigbio:dateModified" : "2014-04-24T21:56:21.981Z"
      },
      {
        "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/000006f6-752f-47ac-8c57-4cb5c57950b8"
        },
        "idigbio:uuid" : "000006f6-752f-47ac-8c57-4cb5c57950b8",
        "idigbio:version" : 0,
        "idigbio:etag" : "d1e6dd8a5fa6eb5a466bdd5ccc27b96c75782383",
        "idigbio:dateModified" : "2014-03-22T11:54:22.227Z"
      },
      {
        "idigbio:links" : {
            "record" : "http://api.idigbio.org/v1/records/0000086b-81ac-4543-845b-306083092c64"
        },
        "idigbio:uuid" : "0000086b-81ac-4543-845b-306083092c64",
        "idigbio:version" : 0,
        "idigbio:etag" : "43bbf1454223820fb3b680417d2aa973f55cdf2f",
        "idigbio:dateModified" : "2014-02-07T20:45:27.947Z"
      }
  ],
  "idigbio:itemCount" : "15324705"
}
</pre>
which includes links to the previous page and next page:
<pre>
<pre>
# CURL SOMETHING
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/records?limit=5&offset=10",
      "idigbio:prevPage" : "http://api.idigbio.org/v1/records?limit=5&offset=0"
  },
</pre>
</pre>


We now have a previous page and a next page, with the offsets of 0 and 10 respectively.
''DO NOT expect to be able to page through the entire iDigBio data this way.  See [[iDigBio API Performance]] if you find yourself trying to page through large amounts of data.''
----
----


Dstoner
1,554

edits

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

Navigation menu