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.

Requesting information

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 Satisfiable error.
  • If you omit the Range header, the API returns an HTTP 206 Partial Content response with the first 20 items.
  • If you specify a valid Range, the API returns an HTTP 206 Partial Content response with the subset requested.

Pre-fetching information

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.