REST API Client Application


    Using the REST API to initiate Sync Gateway Replication

    Related Sync - REST API topics: Public REST API | Admin REST API

    Whether you’re developing a web application getting data from the Sync Gateway API or integrating it with another system you will almost certainly need an HTTP library to consume the Public and Admin Sync Gateway REST APIs. The documentation for the Sync Gateway REST APIs is using Swagger which is a great toolkit for writing REST API documentation, and also to generate HTTP libraries. This guide will walk you through how to start using those libraries to display documents stored in Sync Gateway on a web page

    We do not guarantee that the swagger spec will be aligned with the latest version of the REST API. The REST API must be considered as the source of truth and in case of any deviations, the REST API will override the swagger spec. So please consider the spec as a starting point and make any relevant changes as needed to ensure that it is in conformance with the REST API.

    Follow the steps below to get Sync Gateway up and running.

    1. Download Sync Gateway

    2. In a new working directory, open a new file called sync-gateway-config.json with the following

          "log": ["HTTP+"],
          "CORS": {
              "maxAge": 1728000
          "databases": {
              "todo": {
                  "server": "http://localhost:8091",
                  "users": { "GUEST": {"disabled": false, "admin_channels": ["*"] } }

      Here, you’re enabling CORS on http://localhost:8000, the hostname of the web server that will serve the web application.

    3. Start Sync Gateway from the command line with the configuration file

      ~/Downloads/couchbase-sync-gateway/bin/sync_gateway sync-gateway-config.json
    4. Insert a few documents using the POST /\{tkn-db}/_bulk_docs endpoint

      curl -X POST http://localhost:4985/todo/_bulk_docs \
                  -H "Content-Type: application/json" \
                  -d '{"docs": [{"task": "avocados", "type": "task"}, {"task": "oranges", "type": "task"}, {"task": "tomatoes", "type": "task"}]}'

    A Simple Web Application

    In this section you will use Swagger JS in the browser to insert a few documents and display them in a list. Create a new file called index.html with the following.

    <!DOCTYPE html>
    <html lang="en">
      <meta charset="UTF-8">
      <ul id="list"></ul>
    <script src="swagger-client.min.js"></script>
    <script src="index.js"></script>

    Install the swagger-js library in your working project.

    Next, create a new file called index.js to start sending requests to Sync Gateway.

    // initialize swagger client, point to a swagger spec
    window.client = new SwaggerClient({
      url: '',
      usePromise: true
      .then(function (client) {;

    Here you’re initializing the Swagger library with the Sync Gateway public REST API spec and promises enabled. Promises are great because you can chain HTTP operations in a readable style.

    In this working directory, start a web server with the command python -m SimpleHTTPServer 8000 and navigate to http://localhost:8000/index.html in a browser. Open the dev tools to access the console and you should see the list of operations available on the client object.

    swagger browser

    All the endpoints are grouped by tag. A tag represents a certain functionality of the API (i.e database, query, authentication).

    The method is a helper function that prints all the tags available. In this case we’d like to query all documents in the database so we’ll use the get_db_all_docs method on the database tag to perform this operation. The helper function is available on any node of the API, so you can write to print the documentation for that endpoint as shown below.

    swagger all docs

    Copy the following below the existing code in index.js to query all the documents in the database and display them in the list.

    client.query.get_db_all_docs({db: 'todo', include_docs: true})
      .then(function (res) {
        var rows = res.obj.rows;
        var list = document.getElementById('list');
        for (var i = 0; i < rows.length; i++) {
          var item = document.createElement('li');
          item.innerText = rows[i].doc.task;
      .catch(function (err) {

    The include_docs option is used to retrieve the document properties (the text to display on the screen is located on the doc.task field). A promise can either be fulfilled with a value (the successful response) or rejected with a reason (the error response). Reload the browser and you should see the list of tasks.

    task list