IDigBio API v1 Examples: Difference between revisions

From iDigBio
Jump to navigation Jump to search
No edit summary
(move api performance to separate page)
Line 144: Line 144:
https://api.idigbio.org/v1/records/4e98d066-f35f-4cc0-ad7c-b5b5f2175521/media?quality=thumbnail  https://api.idigbio.org/v1/mediarecords/4c4c5008-5444-4348-85f5-34112b46169b/media?quality=web
https://api.idigbio.org/v1/records/4e98d066-f35f-4cc0-ad7c-b5b5f2175521/media?quality=thumbnail  https://api.idigbio.org/v1/mediarecords/4c4c5008-5444-4348-85f5-34112b46169b/media?quality=web


=== Understanding the performance limits fetching list of records from the iDigBio API ===
=== API Performance ===


While fetching a single record does not require computation, fetching a list of record IDs (endpoints) varying the amount of records in the response and the starting record offset, requires different amounts of computation that leads to certain performance limits. The graphs below give you an understanding of these limits, enabling you to code in the most efficient manner depending on your needs. All graphs show the average response time of a request (blue lines; left side axis) and the number of requests that terminate with a time out exception (red lines; right side axis). Varying the number of parallel requests, we can observe that iDigBio can easily handle 60 concurrent users for requests with the first 1,000 record endpoints; this limit drops to 20 concurrent users if the requests are for larger responses containing a 10,000 record endpoints. Response time also varies with the offset of the request. With 10 concurrent users, the limit is around at the 10-million offset. The current timeout for requests is 50 seconds. Thus, the number of requests terminating with timeout increase as you get close to this limit. It is recommended that you code with retries and back-off mechanisms when you encounter timeout situations.
For large numbers of records, please use the Download system available via the search portal.


https://www.idigbio.org/sites/default/files/working-groups/cywg/api/RecordRetrieval_1000batch_VaryingParallelism.png
See also [[iDigBio API Performance]]
https://www.idigbio.org/sites/default/files/working-groups/cywg/api/RecordRetrieval_10000batch_VaryingParallelism.png
https://www.idigbio.org/sites/default/files/working-groups/cywg/api/RecordRetrieval_1000batch_10Parallelism_VaryingOffset.png

Revision as of 09:38, 6 May 2014


See IDigBio API for documentation on the APIs beyond what is provided here.


For best sampling of JSON results in a browser, you may wish to use the JSONView Extension for Chrome and Firefox.

Most of our examples here will look at a text-based version of the data.

Fetch A Single Record from the API

Example URL:

http://api.idigbio.org/v1/records/c93ebbee-64b5-4452-9e80-93bbfb11b815


In this example we use the curl command-line utility to fetch a single record from the API using the record's iDigBio uuid, then pipe the output to a JSON pretty printing program for human readability.


Example API Results: 

$ curl -s http://api.idigbio.org/v1/records/c93ebbee-64b5-4452-9e80-93bbfb11b815 | json_pp
{
   "idigbio:uuid" : "c93ebbee-64b5-4452-9e80-93bbfb11b815",
   "idigbio:etag" : "9c1eb0e2c0b94543f69dad5005f700d77f118ff7",
   "idigbio:links" : {
      "owner" : [
         "872733a2-67a3-4c54-aa76-862735a5f334"
      ],
      "recordset" : [
         "http://api.idigbio.org/v1/recordsets/6bb853ab-e8ea-43b1-bd83-47318fc4c345"
      ]
   },
   "idigbio:version" : 10,
   "idigbio:createdBy" : "872733a2-67a3-4c54-aa76-862735a5f334",
   "idigbio:recordIds" : [
      "6bb853ab-e8ea-43b1-bd83-47318fc4c345\\6CB7D2F5-C76E-43FD-BACD-097EC550BA18"
   ],
   "idigbio:dateModified" : "2014-04-01T23:17:14.780Z",
   "idigbio:data" : {
      "dwc:catalogNumber" : "125191-Mollusca",
      "dwc:specificEpithet" : "gibberulus",
      "dwc:class" : "Gastropoda",
      "dwc:occurrenceID" : "6CB7D2F5-C76E-43FD-BACD-097EC550BA18",
      "dwc:infraspecificEpithet" : "gibbosus",
      "dwc:recordedBy" : "Kohr, H. H.",
      "dwc:scientificName" : "Strombus gibberulus",
      "dwc:family" : "Strombidae",
      "dwc:basisOfRecord" : "PreservedSpecimen",
      "dwc:collectionCode" : "Invertebrate Zoology",
      "dcterms:modified" : "03/21/2014",
      "dwc:decimalLongitude" : "144.8",
      "dwc:country" : "USA",
      "dwc:scientificNameAuthorship" : "Röding",
      "dwc:locationID" : "ZZZ-072834",
      "dwc:stateProvince" : "Mariana Islands",
      "dwc:genus" : "Strombus",
      "dwc:decimalLatitude" : "13.5",
      "dwc:institutionCode" : "FLMNH",
      "dwc:order" : "Mesogastropoda",
      "dwc:county" : "Guam Island"
   }
}


Fetch five MediaRecord IDs (endpoints) from the API

Example URL:

http://api.idigbio.org/v1/mediarecords?limit=5

Example API Results: 

 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" : 2,
         "idigbio:etag" : "c13b10675b4a83031b1dc7a24c1f5c4e443b1939",
         "idigbio:dateModified" : "2014-04-03T17:43:18.145Z"
      },
      {
         "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" : 0,
         "idigbio:etag" : "0357f74dada8b21a69281b042a52f47a172fa33b",
         "idigbio:dateModified" : "2014-01-20T20:19:29.754Z"
      }
   ],
   "idigbio:itemCount" : "2199334"
}



To Do: Provide examples of displaying multiple images accessed via the mediarecord API endpoint.

https://api.idigbio.org/v1/records/4e98d066-f35f-4cc0-ad7c-b5b5f2175521/media?quality=thumbnail https://api.idigbio.org/v1/mediarecords/4c4c5008-5444-4348-85f5-34112b46169b/media?quality=web

API Performance

For large numbers of records, please use the Download system available via the search portal.

See also iDigBio API Performance

Retrieved from "http://www.idigbio.org/wiki/index.php?title=IDigBio_API_v1_Examples&oldid=9509"