Since requests for resources can yield large quantities of data, you may need to split requests to HTTP endpoints into multiple calls. The API implements a subset of the HTTP Range Request standard. This includes a
Range header you can specify when making a request, and a
Content-Range header that’s included in the response from any endpoint.
The Range header lets you access collections of resources as zero-indexed arrays. The example below requests the first 10 resources (0-9):
$ curl -X GET 'https://public.enigma.com/api/collections/' \ -H 'Authorization: Bearer <APIKEY>' \ -H 'Range: resources=0-9'
Other examples of valid ranges include:
'Range: resources=0-': All items in the collection (subject to a 1,000 item limit).
'Range: resources=9-': From item 10 to the end of the collection (also subject to a 1,000 item limit).
When requesting information, be aware that:
- You may request up to 1,000 items with each HTTP request.
- If you request more than 1,000 items, the API returns an
HTTP 416 Range Not Satisfiableerror.
- If you omit the
Rangeheader, the API returns an
HTTP 206 Partial Contentresponse with the first 20 items.
- If you specify a valid Range, the API returns an
HTTP 206 Partial Contentresponse with the subset requested.
It may be useful to know the number of resources that will be returned before making a request. You can do this using the
HTTP HEAD method on any endpoint. The
HEAD method returns the headers that would be returned with the response. This includes the
Content-Range header with the total number of items, subject to any URL parameters, etc., so you can know the number of items before transferring them.
For example, to determine how many top-level collections exist, send a
HEAD request to the
/collections/ endpoint. The response might include something like this:
Content-Range: resources 0-9/29
In this example, the
Content-Range header indicates that the first 10 collections out of a possible 29 would be included in the response.