POST to _changes

The Couchbase Sync Gateway allows the POST method to be used with /db/_changes. The parameters are passed in the request body (as JSON) rather than as URL queries.

Why is this necessary?

The parameters to _changes can be arbitrarily large. In particular, some server implementations have sequence IDs that are lengthy opaque strings (instead of numbers), which then have to be passed in the since parameter. Filters can also take arbitrary named parameters, with no limit on their length; in particular the Sync Gateway uses a filter parameter that's a list of channels to pull from, and it's possible this could grow lengthy.

This can cause problems with HTTP gateways or proxies that impose limits on URL length. The request may be rejected, causing replication to fail.

The POST format also makes it more straightforward to send filter parameter values that are types other than strings. In some cases there is a convention of JSON-encoding a filter parameter, but this can create ambiguities, for example whether ?foo=123 has a number or a string as a value. It also results in long and human-unreadable URLs as JSON punctuation gets percent-encoded.

Request Format

POST /db/_changes
Content-Type: application/json

{"param1": value1, "param2": value2, ...}

The URL query parameters normally appended to _changes are omitted (and the server will ignore any that are present). Instead, the same parameters and values go into a JSON object in the body of the request:

• Parameter names are unchanged.
• Values should be expressed in native JSON, not necessarily as strings: for example, heartbeat's value should be a number, and include_docs a boolean. The value of since should be exactly as returned in the last_seq property in the server's previous response.

Compatibility

This feature was added to the Couchbase Sync Gateway (and Couchbase Lite for iOS) after the 1.0 beta 2 release. It will be present in the 1.0 release and onwards.

No other implementations are known.