Conditional GET Requests

Some services, such as the Standard Fields service and the Custom Fields service, support conditional GET requests that only return a response body if the corresponding data has been modified since the Last-Modified timestamp or the ETag was generated.

This feature is especially useful when caching data locally in your application, as it will allow you to check the staleness of your cached data with a potentially lightweight request, while providing you with fresh data if stale.

Last-Modified/If-Modified-Since

Resources that allow a conditional GET request will always respond with a Last-Modified header when a response body is sent. In subsequent requests, pass this value in the If-Modified-Since request header to only receive a response body if the data has changed since the the provided time. If the data is not stale, an HTTP 304 response will be returned, with an empty body.

See this in action in the example below. Note that the response body is omitted from the first example purely for brevity.

$ curl "https://sparkapi.com/v1/standardfields" -H "Authorization: OAuth MY_OAUTH2_ACCESS_TOKEN" {} -D -

HTTP/1.1 200
Date: Thu, 14 Aug 2014 18:35:57 GMT
ETag: "c94df465e7f9dc849cfb724967d63ebd"
Last-Modified: Tue, 12 Aug 2014 15:42:08 GMT
Status: 200

$ curl "https://sparkapi.com/v1/standardfields" -H "Authorization: OAuth MY_OAUTH2_ACCESS_TOKEN" -H "If-Modified-Since: Tue, 12 Aug 2014 15:42:08 GMT" {} -D -

HTTP/1.1 304
Date: Thu, 14 Aug 2014 18:38:42 GMT
ETag: "c94df465e7f9dc849cfb724967d63ebd"

ETag/If-None-Match

Resources that allow a conditional GET request will always respond with a ETag header when a response body is sent. Like the Last-Modified example above, if the If-None-Match request parameter is supplied with this value, a response body will only be returned if the data has been updated since the ETag was generated. Otherwise, an HTTP 304 response will be returned, with an empty body.

See this in action in the example below. Note that the response body is omitted from the first example purely for brevity.

$ curl "https://sparkapi.com/v1/standardfields" -H "Authorization: OAuth MY_OAUTH2_ACCESS_TOKEN" {} -D -

HTTP/1.1 200
Date: Thu, 14 Aug 2014 18:35:57 GMT
ETag: "c94df465e7f9dc849cfb724967d63ebd"
Last-Modified: Tue, 12 Aug 2014 15:42:08 GMT
Status: 200

$ curl "https://sparkapi.com/v1/standardfields" -H "Authorization: OAuth MY_OAUTH2_ACCESS_TOKEN" -H "If-None-Match: \"c94df465e7f9dc849cfb724967d63ebd\"" {} -D -

HTTP/1.1 304
Date: Thu, 14 Aug 2014 18:38:42 GMT
ETag: "c94df465e7f9dc849cfb724967d63ebd"