API documentation

Revs and ETags

The Nutshell API offers solutions for cache validation at the network and application levels.


Nutshell uses HTTP ETags as a solution for cache validation at the network level. The JSON-RPC API uses ETags as specified in HTTP 1.1, and is useful for simple API optimizations at the network layer.

When a get* or find* method is requested via JSON-RPC with the current ETag in the If-None-Match header, the server will respond with an empty response and a 304 (not-modified) HTTP status. If the document has changed, the response will contain the full requested contented and the new Etag header.

Note that ETags are currently not relevant (and ignored) for edit methods. Use the rev key documented below for version checking.


Revs are Nutshell's approach to application-level cache control.

The Nutshell API issues a revision identifier (rev key) as part of its response each time you retrieve an entity. Your API client should store this identifier with its cache of the entity.

Note: Revs may appear to be incrementing integers, but your application should treat revs as strings to avoid potential issues in the future.

When you call a potentially-destructive API method (for example, editContact), you must include the rev that you have cached for the entity you are modifying. If that rev doesn't match the rev on the server, the entity has been updated on the server since you last retrieved it. In that case, you won't be allowed to make the change you requested; you'll need to download the latest version of the entity, resolve any conflicts, and retry your edits.

If the entity has been modified since you last downloaded it, you'll get the error "rev key is out-of-date":

"error": {
    "code": 409,
    "message": "rev key is out-of-date",
    "data": NULL

When you call a non-destructive API method (for example, getContact) to retrieve an entity you already have cached, you can send the rev that you have for that entity. If the entity hasn't been modified on the server, the API will not return the whole entity again. Instead, it'll include a _notModified attribute in the result:

"result": {
    "entityName": "Contacts",
    "id": 10,
    "rev": "5",
    "_notModified": true

Sometimes, you may want to perform a destructive edit or explicitly ignore Nutshell's revs for some other reason. This is possible, though you should exercise caution when using this functionality. To tell the Nutshell API to ignore revs, pass the string "REV_IGNORE" as the rev of the entity you intend to edit.