Some clarification required on Sync Gateway (Replication, external integration, REST API)

Hi there,

we are considering to utilize CouchBase Mobile as a reliable messaging layer for connecting edge devices/apps. There are some questions that I couldn’t find the solution in the docs though.

  1. What is the main use case for the Public REST API of Sync Gateway since moving to a websocket/BLIP-based replication protocol in v2.0? My understanding is that the REST API was modeled after the CouchDB API which used to be the foundation for replication which isn’t the case anymore.
  2. The webhook documentation states that document changes made through the REST API can trigger events for downstream processing. I assume that this also applies to doc changes made through the new replication protocol. Can anyone confirm this?.
  3. Under “Running replications”, there seems to be some unclear documentation.
    3.1. Assuming we are running two couchbase server clusters (separated by an unreliable network) that need to be synchronized, what is the preferred approach (with pro’s and con’s) ? It seems, both SG_Replicate (between SG instances) or XDCR can be used, but it is not clear when to use what.
    3.2. The same page states that replication between two SG instances actually uses the REST API. I was of the impression that everything had been moved to the new replication protocol based on websockets. It seems this is only valid between CouchBase Lite and SG though.
  4. Regarding Admin vs Public REST API, there seems to be significant overlap. The Admin REST API contains 10 endpoints, 7 of which are also covered by the Public REST API. When to use what ?

Sorry if any of my questions have already been addressed somewhere.

Thanks in advance, Nick

As an update, I found the following statement here.

“•The Public REST API is used for client replication. The default port for the Public REST API is 4984.”

Related to my first above question, does this imply that the Public REST API is essentially obsolete now? Accessing the change feed server side can be done via the Admin REST API on port 4985.


  1. The public REST API continues to manage authentication and should be the means by which clients communicate with Sync Gateway. Clients using the 2.0 replication authenticate over the public REST API before having that request promoted to a websocket that manages the 2.0 replication.

  2. Yes, this applies to any document writes made via Sync Gateway.

3.1. sg-replicate should be used for replication between mobile-enabled Couchbase Server buckets. There are scenarios where uni-directional XDCR will work, but in general it’s not recommended for mobile-enabled buckets.

3.2. Correct - currently the new replication protocol is only used between Couchbase Lite and Sync Gateway.

  1. The primary difference between the Admin API and the public API is security - public API calls are executed in the context of an authenticated user, admin API calls are executed with admin rights. The Public API is typically internet-facing, the Admin API should only be available for internal, secure access.

Hi Adam,

thanks for your answer, very helpful.

couple of follow up’s:

  1. Does that imply that eventually all non-security/auth related endpoints will be phased out of the Public REST API, and clients should only use “auth” and “session” endpoints going forward?

3.1. Can you define “mobile-enabled bucket”? Let’s say, I have three components: a native app (with CBL), a sync gateway incl. Couchbase server (in DC1) and another CouchBase cluster (in DC2). The client exchanges data with the DC1 cluster via sync gateway. From there, the data needs to be replicated to the other CouchBase cluster in Dc2 (Let’s assume, the second cluster is not directly accessed by mobile clients and there is no sync gateway in Dc2). I would have thought that XDCR would be the preferred solution for the latter part, but then again, the first cluster is “mobile enabled” which indicates SG-Replicate according to your answer. If correct, this would imply installing another sync gateway without having to support mobile clients. Confused :wink:

  1. The security dimension is one differentiator which is covered at the network level (i.e. different ports --> different API’s). The necessary use cases are another dimension affecting which endpoints are exposed. As per my comment above, if the only remaining use case for the internet facing Public REST API is to create the authenticated user context , then does this imply that the other endpoints are obsolete and will eventually be removed?