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 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.

Another issue is that some servers or intermediate proxies may log all request URLs, which presents possible privacy concerns if sensitive data is contained in filter parameters (such as channel names in the case of the Sync Gateway.)

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.