Conditional Requests

Where responses reference non-ephemeral resources, such as packages, the API will return an ETag header that represents a uniqueness identifier for the results. If an ETag is sent, then the API might also send a Last-Modified header if it knows when the resource was last updated, but it's better to rely on the ETag alone. A client can send the If-None-Match header with the value of the known ETag to avoid returning the full resource again, in which case a match will result in a 304 Not Modified status being returned instead.

Let's see it in action:

curl -i -H "X-Api-Key: foobar" https://api.cloudsmith.io/user/self/

HTTP/1.0 200 OK
Content-Type: application/json
ETag: "99ed160b320d4daa29fcd6097de8cdAf"
Connection: close
Server: Cloudsmith MCP
Date: Sun, 29 Jan 2017 23:56:34 GMT

{
  "authenticated": true,
  "slug": "example",
  "slug_perm": "ABbx54bagaAB",
  "name": "Example User",
  "email": "[email protected]"
}

curl -i -H "X-Api-Key: foobar" -H "If-None-Match: 99ed160b320d4daa29fcd6097de8cdAf" https://api.cloudsmith.io/user/self/

HTTP/1.0 304 Not Modified
content-type: text/plain
ETag: "99ed160b320d4daa29fcd6097de8cdAf"
Server: Cloudsmith MCP
Date: Sun, 29 Jan 2017 23:57:20 GMT

📘

Rate Limiting

If If-None-Match or Is-Modified-Since (where Last-Modified was sent) is used and results in a 304 Not Modified response, the client will not incur any changes to their current rate limit usage. In other words, unmodified resources do not count towards rate limits.