Client supplied _rev property in document when updating via Sync Gateway REST API

Mobile Sync Gateway
1

We have a web + mobile application that we’re upgrading from CouchDB to Couchbase / Sync Gateway. To ease the transition, the web application continues to use the Sync Gateway REST API (v2.8 for now, planning to move to v3.0) rather than SDK, since it is so similar to CouchDB’s. The mobile applications (Android & iOS) are using Couchbase Lite 3.0.

As a minimal “hack” to work with our existing code, we modified some of our views to add _id and _rev properties to the returned documents, populating them from meta().id & meta().rev, respectively.

The _rev property seems to be required by SG when PUTting an updated document via the REST API, so I assume that this shouldn’t be a problem. We can filter ou the _id property if necessary.

My question is are we doing this correctly, or do we need to do it a different way?

The documentation for Couchbase says that properties with a leading _ are reserved and creating documents with these fields will trigger an exception.

The Sync Gateway Public REST API shows the document with those fields.

The Sync Gateway Data Modelling documentation says it will be rejected.

The Couchbase Document Constraints doc says it will trigger an error.

If I try to PUT an updated document without a _rev property via the Sync Gateway REST API (using curl) it fails with a conflict error:

HTTP/1.1 100 Continue

HTTP/1.1 409 Conflict
Content-Type: application/json
Server: Couchbase Sync Gateway/2.8.2 CE
Date: Fri, 09 Dec 2022 23:23:43 GMT
Content-Length: 47

{"error":"conflict","reason":"Document exists"}

If I add the _rev property (with the previous document’s value for that field), then it succeeds.

So what’s the right thing to do here?

2

_id and _rev (along with a few other CouchDB-isms like _deleted) are accepted in document bodies on Sync Gateway’s REST API for backwards compatibility, but shouldn’t be considered part of the actual document body that ends up being written (i.e. user-data)

There are alternative ways of specifying this data (e.g. in a ?rev=1-abc query parameter) but either way is fine!

3

Thank you for the clarification. The documents are confusing on this issue, as I mentioned in the original question.