Test Couchbase Sync Gateway REST API interface using Postman

The Couchbase Sync Gateway is one of the core components of the Couchbase Mobile stack. At a high level, it is responsible for securely routing and syncing data between web and mobile clients and Couchbase server. It supports a REST API that allows clients to perform admin and non-admin operations on the Couchbase Server database. If you are developing a client app that interfaces with the Sync Gateway, then you would need a convenient way to explore the API and to test it out, probably even mocking all the calls to the Sync Gateway.  We can use Postman for this purpose.

Postman is an API Test, Development and Documentation tool. The Sync Gateway supports Postman collections corresponding to its Admin and Public REST interface. In an earlier post, we covered the basics of how to get started with Postman for Sync Gateway API testing. There have been substantial improvements to the Sync Gateway Postman Collections since then and of course, there have been changes to Postman itself. This post discusses the enhancements to the Collection definitions. The post also includes a video demonstration.

Everything discussed in this post uses the free community version of the Postman tool.

Background

The Couchbase Mobile Stack comprises the Couchbase Server, Couchbase Sync Gateway and Couchbase Lite embedded Database. This post assumes that you’re familiar with the Couchbase Mobile stack. If you want to read up more on Couchbase, you can check out the resources on our Couchbase website.
The post also assumes you have a basic understanding of using Postman. If you want a refresher, please check this out.

TL;DR

If you prefer, you can check out the video below which is a demonstration of everything that is discussed in this blog post.

Installing Postman

Before proceeding, you must download and install the Postman tool. You will also need to create a free account.

Importing the Sync Gateway Postman Collection

Getting started with using Postman with Sync Gateway is very easy.

• First, download the Sync Gateway postman collections from the GitHub repo

• Follow the instructions detailed in this introductory post to import the collections and environment files into Postman. At the end of it, your setup should look something like this.
  

Running Mock Requests

You can test Sync Gateway API with Postman without even having a Sync Gateway running in your environment. Note that Postman imposes limits on the number of mock calls that you can do using the free account. So if this is something that you plan to use extensively, you may have to go to the Pro version of the tool.

Create a mock Sync Gateway

• Follow the instructions here to add a mock server. It is literally a one-button click to create a mock server
  
• Examine the Sync Gateway Postman environment variables. The “adminurl” points to the Admin URL endpoint and the “publicurl” points to the Public URL endpoint. Update these variables to point to the newly created mock server
  
• That’s it! You are ready to run your request against your mock server

Running a request with Postman against a mock sync gateway server is an example

How are the mock Postman responses generated and how does Postman cache responses?

The Sync Gateway collection comes with pre-built responses that you can locate in the “examples” folder. This response is returned when you test out against the mock server. You can use the sample responses in the “examples” folder as a reference even without actually running the requests.

Postman Tests

Every request has an associated test script. The tests are fairly straightforward and for the most part check the HTTP status code. You can extend these tests to do more extensive processing of the response.

Testing with a Sync Gateway Instance

While mock testing is great for API exploration and during early development, it isn’t the equivalent of testing against the real system!

• If you haven’t already done so, go ahead and download Sync Gateway instance and/or Couchbase Server
  • Follow instructions here to download and install the Sync Gateway. If you want to persist your data in Couchbase Server, then follow the instructions in this quick start guide to installing Couchbase Server.
  • If you prefer using Docker, you can follow instructions here to get started with Couchbase Mobile using Docker.
• There is a sample sync-gateway-config file that is available in the same Collections GitHub repo that you pulled earlier. The configuration values specified in the sample config file corresponds to the default environment variables. So if you want to use the default values in the environment file, you can launch the sync gateway with the sample sync-gateway-config file.
• Update the “adminurl” and “publicurl” to point to the admin and public endpoints of your sync gateway deployment.
• If you launched your Sync Gateway with a configuration file that is different than the sample sync-gateway-config file, then in addition to updating the “adminurl” and “publicurl” variables, make sure you update the other relevant environment variables to match your configuration. Some of them include “db”, “name”, “password” and “doc”

That’s it – you are ready to test against a live system!

Request Chaining

One of the cool things that we support in our collections is request chaining – i.e. the output of a request can be used as input to a subsequent request. This is accomplished by dynamically updating the environment variables with the results of request execution without the need to manually edit the requests.

For example,
– When you create a document, a new document revision is created and the revisionID of the newly created revision is returned in the response in the “_rev” field. We have a test that extracts the “_rev” value and sets the “rev” environment variable

• Subsequent request to update the document requires the revisionID to be specified in the request. This is retrieved from the “rev” environment variable that was populated as a result of the previous execution request.

Client Postman Code Snippets

Another useful feature in using Postman client is the “Code snippet generator”. You can generate code snippets corresponding to the requests in one of the many supported languages

Postman Documentation Generator

The API documentation on our Couchbase developer portal should be considered the source of truth.

However, if you would like to view a “web version” of the documentation generated by Postman corresponding to your collection. You can do so by selecting the “view in web” option. Note that your local postman client should be “in sync” with your online postman account.

The generated documentation would look similar to this. You would need an account on Postman to be able to view the documentation.

Next Steps

If you see an issue in the collections definitions or if you would like to enhance it with additional tests, please submit a Pull Request to the Github Repo.

If you have questions or feedback, please leave a comment below or feel free to reach out to me at Twitter @rajagp or email me priya.rajagopal@couchbase.com.  The Couchbase Forums are another good place to reach out with questions.