This post discusses a convenient way to query, explore and test the REST API exposed by the Couchbase Mobile Sync Gateway using the Postman Chrome Developer tool. Sync Gateway exposes a REST, Batch & Stream interface that allows clients interact with it over the Internet.

 

NOTE:  We will be discussing Couchbase Mobile v1.4 which is the current production release. There is a newer Developer Preview version 2.0 of Couchbase Mobile

 

Background

Couchbase Sync Gateway is part of the Couchbase Mobile stack and is an Internet-facing synchronization mechanism that securely syncs data across devices as well as between devices and the cloud. There are two ports over which the Sync Gateway listens to requests- The Admin port (defaults to 4985) and the Public port (defaults to 4984). In production deployments, the admin port is typically blocked from access over the Internet.

Installation of Couchbase Sync Gateway

Please follow instructions in the blog post to install the the Sync Gateway in your Mac OS development environment. See the downloads site for all the available packages, and the full installation guide for complete details. To install on Linux distributions other than the supported ones, see this post.

 

Installation of Postman

Postman is a Chrome Developer tool that can be downloaded for free from the Chrome browser web store .

Using Postman to Query the Couchbase  Sync Gateway

  • Get the Postman collections

The Postman collection files and environment definition for the Admin and Public interface of the Sync Gateway is available for download from this Github Repo.

There should be three files:-

Sync-Gateway-Admin.postman_collection 

This is the Portman collection corresponding to the Admin interface of the Sync Gateway

Sync-Gateway-Public.postman_collection

This is the Portman collection corresponding to the Public interface of the Sync Gateway

Sync-Gateway-Environment.postman_environment

This is the Environment Definitions file that defines the variables used by the Admin and Public collections

Launch the Postman App

  • Import the collections

Follow the steps in the video below to import the collections that were downloaded in the previous step.

Importing Sync gateway postman collections

  • Import the environment file

Follow the steps in the video below to import the environment definition corresponding to the Postman collections

  • Set the appropriate environment

Follow the steps in the video below to set the environment to the one that you just imported. Update the values of the variables to suit your environment. Make sure that the adminurl points to the Sync Gateway at Admin Port and the publicurl variable points to the Sync Gateway at Public port. It defaults to http://localhost:4985 and http://localhost:4984 respectively.

  • That’s it!  Run your queries

The following is a demonstration of running a request on the Admin Interface

 

The following is a demonstration of running a request on the Public Interface. Make sure you set the authorization header is set appropriately to use the appropriate authentication mechanism.

Querying Sync Gateway Public Interface

Querying the Public Interface of Sync Gateway

CLI Option

If you are interested in executing the Postman Collection from the command line interface, which may be the case for instance, if you want to integrate this as part of your Continuous Integration process, then you should check out  Newman, which is CLI runner for Postman.

For example, the command below will run the Sync-Gateway-Admin.postman_collection with the Sync-Gateway-Environment file.

If your Sync Gateway is running with SSL enabled and is using a self-signed certificate, the “-k” option will suppress validation of the cert (“insecure” SSL connection). This is not recommended in production environments.

 

 

 

Next Steps

The Postman Collections provide an easy way to query, explore and test the REST interface exposed by the Sync Gateway. If you see an issue in the collections definitions or if you would like to enhance it, please submit a Pull Request to the Github Repo.

If you have further questions, feel free to reach out to me at Twitter @rajagp or email me priya.rajagopal@couchbase.com.

The Couchbase Mobile Dev Forums is another great place to get your mobile related questions answered .

Also, checkout out the Couchbase Sync Gateway API Definitions for details on the web interface.

 

Author

Posted by Priya Rajagopal, Senior Director, Product Management

Priya Rajagopal is a Senior Director of Product Management at Couchbase responsible for developer platforms for the cloud and the edge. She has been professionally developing software for over 20 years in several technical and product leadership positions, with 10+ years focused on mobile technologies. As a TISPAN IPTV standards delegate, she was a key contributor to the IPTV standards specifications. She has 22 patents in the areas of networking and platform security.

All Posts

2 Comments

  1. atom992 April 17, 2017 at 5:34 pm

    good example, postman is a good tools to understand Sync Gateway REST API, it is also a good test tools to test your Sync Gateway business logic.
    If you like CLI to run test user case,I recommend [newman](https://github.com/postmanlabs/newman) to run postman collections,which was the tools I am using for test my sync gateway logic.
    I want to share a little tips for using newman to test sync gateway logic:
    add 300ms for –delay-request to avoid query _changes feed with “normal” and “since” returns empty results first time.
    see also https://github.com/couchbase/sync_gateway/issues/2452

    1. Priya Rajagopal April 18, 2017 at 7:56 am

      Thanks ! Good point. I have added a section on CLI option

Leave a reply