IDigBio API v1 Specification: Difference between revisions

Jump to navigation Jump to search

IDigBio API v1 Specification (view source)

Revision as of 10:14, 20 May 2014

5,475 bytes added ,  20 May 2014
add usage examples →‎GET /v1/mediarecords
(add usage examples →‎GET /v1/mediarecords)
Line 130: Line 130:
|limit
|limit
|
|
|
|Controls the number of records returned by a collection url. Large values may cause HTTP requests to time out.
|-
|-
|offset
|offset
|
|
|
|Controls the starting record offset paging through the API. Large offsets are extremely inefficient, so combinations of small limits and large offsets may cause requests to fail.
|}
|}
;Sample Usage
;Sample Usage
Request the first 5 media records:
<pre>
$ curl -s "http://api.idigbio.org/v1/mediarecords?limit=5" | json_pp
{
  "idigbio:errors" : [],
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=5"
  },
  "idigbio:items" : [
      {
        "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/000003cd-0cca-421b-8f26-f557a26b0393"
        },
        "idigbio:uuid" : "000003cd-0cca-421b-8f26-f557a26b0393",
        "idigbio:version" : 1,
        "idigbio:etag" : "ce3e2f7272ec996bb479c87549ba90c15ba96426",
        "idigbio:dateModified" : "2014-04-21T22:19:27.436Z"
      },
      {
        "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00000728-ffb3-4a68-9f93-137f19961121"
        },
        "idigbio:uuid" : "00000728-ffb3-4a68-9f93-137f19961121",
        "idigbio:version" : 3,
        "idigbio:etag" : "ef2cac326a60d89d8cb9005abaa82068bfa83565",
        "idigbio:dateModified" : "2014-04-24T05:03:56.782Z"
      },
      {
        "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00000b03-e208-4d22-983b-506ad2842f7c"
        },
        "idigbio:uuid" : "00000b03-e208-4d22-983b-506ad2842f7c",
        "idigbio:version" : 2,
        "idigbio:etag" : "bc118a7ea53e004c82ab9b7e813e1010ae5f8e17",
        "idigbio:dateModified" : "2014-04-20T05:16:20.389Z"
      },
      {
        "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/000010bc-a4d4-483d-b71d-0dbdd4fd2d5a"
        },
        "idigbio:uuid" : "000010bc-a4d4-483d-b71d-0dbdd4fd2d5a",
        "idigbio:version" : 0,
        "idigbio:etag" : "68c441bd3c49507bf930f3b278f2c58f9cb792ec",
        "idigbio:dateModified" : "2014-04-20T21:38:46.679Z"
      },
      {
        "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/000012f9-d288-4a14-b898-77430e0a137a"
        },
        "idigbio:uuid" : "000012f9-d288-4a14-b898-77430e0a137a",
        "idigbio:version" : 1,
        "idigbio:etag" : "cf49416750fdb9bdb808c334a74b84f27bb8160b",
        "idigbio:dateModified" : "2014-04-23T02:43:08.344Z"
      }
  ],
  "idigbio:itemCount" : "2342880"
}
</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 2,342,880 mediarecords total.
We are also provided with a link to the next "page" of records:
<pre>
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=5"
  }
</pre>
We then request the next 5 records:


<pre>
<pre>
# CURL SOMETHING
$ curl -s "http://api.idigbio.org/v1/mediarecords?limit=5&offset=5" | json_pp
{
  "idigbio:errors" : [],
  "idigbio:links" : {
      "idigbio:nextPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=10",
      "idigbio:prevPage" : "http://api.idigbio.org/v1/mediarecords?limit=5&offset=0"
  },
  "idigbio:items" : [
      {
        "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00001478-c150-4faf-a617-439a838d4377"
        },
        "idigbio:uuid" : "00001478-c150-4faf-a617-439a838d4377",
        "idigbio:version" : 1,
        "idigbio:etag" : "30f602e4eb47ebb2ceb265f64217e3cf5664f517",
        "idigbio:dateModified" : "2014-03-21T23:09:39.752Z"
      },
      {
        "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00001a91-189b-4002-b56e-a770a55951a0"
        },
        "idigbio:uuid" : "00001a91-189b-4002-b56e-a770a55951a0",
        "idigbio:version" : 0,
        "idigbio:etag" : "647e82d17ee435fb14f0f8607dabe88dfc3a1944",
        "idigbio:dateModified" : "2014-04-25T04:49:32.359Z"
      },
      {
        "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00002091-4fb3-410a-9307-bd3e917dfcca"
        },
        "idigbio:uuid" : "00002091-4fb3-410a-9307-bd3e917dfcca",
        "idigbio:version" : 0,
        "idigbio:etag" : "90d98d48d9e7e07eab9064bd9b6e22ce6502c07f",
        "idigbio:dateModified" : "2014-05-03T18:45:47.112Z"
      },
      {
        "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00002c32-ae3a-41ed-9bd9-f6c50d3e35fb"
        },
        "idigbio:uuid" : "00002c32-ae3a-41ed-9bd9-f6c50d3e35fb",
        "idigbio:version" : 3,
        "idigbio:etag" : "d1ded90d06e93876b1badd01222905add93e8806",
        "idigbio:dateModified" : "2014-04-19T00:25:59.471Z"
      },
      {
        "idigbio:links" : {
            "mediarecord" : "http://api.idigbio.org/v1/mediarecords/00002dbd-6415-463b-8cae-38f548415ffa"
        },
        "idigbio:uuid" : "00002dbd-6415-463b-8cae-38f548415ffa",
        "idigbio:version" : 2,
        "idigbio:etag" : "4e298045b496146f5c51e331c9887fd7afde4deb",
        "idigbio:dateModified" : "2014-04-21T20:29:39.531Z"
      }
  ],
  "idigbio:itemCount" : "2342880"
}
</pre>
</pre>


''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/9950"

Navigation menu