Postman Collections for Sync Gateway Administration

Web-based clients can administer, monitor and interact with Couchbase Sync Gateway using a RESTful interface. With the Sync Gateway 3.0 release, database administration is done exclusively through the admin REST endpoint. Postman is an API test, development and documentation tool that allows you to test and use these endpoints.

This blog post shows you how to use the Postman API client to configure, administer, and interact with Sync Gateway via the REST interface.

Postman Collections for Sync Gateway

A Postman Collection is a group of saved requests organized in folders and subfolders. You can use collections as a starting point and customize them to your environment and needs. 

We have produced a reference set of Postman collections and corresponding environment variable definition files for the REST interface of Sync Gateway 3.0. These files are available on Github and designed to get you up and running quickly with the following steps.

First, clone the repository

The repository also contains a travel-sample folder and a custom collection for the Travel Sample application, as we discuss a little later.

Now let’s explore the other contents of the cloned repo. There are three Postman Collection JSON files with the suffix postman_collection.json included and a Postman Environment settings file as described in this table:

Using the Postman Client

• Download the Postman client for free for your platform. 
• Follow the instructions detailed in this introductory post to import the collections and environment files into Postman. 
• Update the environment file settings per your deployment and start executing requests against Sync Gateway.

At the end of it, your setup should look something like the following screenshot:

Administer Sync Gateway via REST API: Example Walkthrough

Once bootstrapped and connected to the Couchbase Server cluster, Sync Gateway is managed via the REST endpoint. We’ll now walk through the process with a concrete example.

The GitHub repository contains a custom version of the Postman collections for managing a Sync Gateway backed by a Travel Sample bucket. The following collections are located in the travel-sample folder.

Viewing Test Results

Most of the requests in the collections include simple tests to verify the success of the request. This screenshot shows the Tests tab that includes the test code and the Test Results console window at the bottom.

Request Chaining

Request Chaining takes the output of a request and uses it as input to a subsequent request. This is accomplished by dynamically updating the environment variables with the results of request execution and removes the need to manually edit requests.

For instance, a new document revision is made when you create a document. The revisionID of the new document is returned via the _rev field. The test associated with the request then extracts the _rev value and sets the rev environment variable.

The screenshot below shows the code that sets the environment variable and the output JSON of the populated Body.

A subsequent update request to the document can retrieve the revisionId of the document to be updated from the rev environment variable that was populated by the previous request.

This screenshot shows a mouseover preview of the value of the rev variable:

Installing Couchbase & Sync Gateway with Docker

To be able to run the collection, you need an environment with Couchbase Server and Sync Gateway. Deploying them in Docker containers is the simplest option. We have pre-built images that have everything pre-configured for you.

Docker must be installed on your machine. On Windows, you may need administrator privileges. Ensure that you have sufficient memory and cores allocated to Docker. At least 3GB of RAM is recommended.

Setting up a Docker Network

Create a docker network named workshop by running these Docker commands

I have a custom Docker image of Couchbase Server that you can use called:

The image comes pre-configured with the travel-sample bucket and three RBAC users:

• admin – that Sync Gateway uses to connect to Couchbase Server
• sgw-cluster – for cluster-level operations via Sync Gateway admin/metrics REST endpoint
• sgw-admin – for Sync Gateway database-level administrative operations via Sync Gateway admin/metrics REST endpoint

Deploy the server using following Docker commands:

Test Couchbase Server Installation

The server would take a few minutes to deploy and fully initialize. Be patient, but you can use this command to check the status:

You should see the following once setup is complete:

Open the Couchbase Web UI URL in a web browser: http://localhost:8091 

On the login screen, sign in as Administrator with password: password.

Go to the Buckets menu and confirm that the travel-sample bucket is loaded. This bucket contains the sample data. You can see the bucket exists and there are many documents loaded in this screenshot:

Go to the Security menu and confirm that our three users are created, as shown below:

Install & Test Sync Gateway 

Sync Gateway needs to be bootstrapped with a startup configuration file. The sync-gateway-config-travelsample-bootstrap.json file is available in the travel-sample folder of the cloned repository.

Switch to the folder that contains the downloaded config file and run the following three commands to stop any running instances of Sync Gateway:

Now, to start Sync Gateway using Docker, run the following commands depending on your operating system. Note the commands are one long line, shown here in multiple lines for readability:

Windows

Non-Windows Machine

Test Sync Gateway Installation

You can confirm that Sync Gateway is up and running by verifying the log messages with Docker:

You will see a bunch of log messages and none of them should be errors.

To confirm that Sync Gateway is running, go to http://localhost:4984 in a web browser.
You should see a message similar to this:

Using Postman

Launch the Postman API client and import all the three travel-sample collections and the corresponding environment file, e.g., Sync-Gateway-3.0-TravelSample-Environment. Spend some time exploring the environment file.

All the requests use the relevant user for authorization. However, you will need to provide a password when running the requests. The users are set up with a password of password. So make sure you configure the Authorization header of your requests with the right password.

Sanity Test

First, let’s do a sanity test to ensure communications are generally working. Run the Get Sync Gateway Info request from the Admin API collection. You should see details of Sync Gateway in the response. The screenshot below shows response in the Body window at the bottom of the screen.

Create & Configure Travel Sample Database on Sync Gateway

Depending on whether we make a cluster-level request or a database-level request, the user specified in the Authorization header may be {{clusteradmin}} or {{dbadmin}} respectively. Use the password of “password” for all requests.

Sync Gateway database administration, including database creation, is handled via the admin REST endpoint and requires a Sync Gateway database to work. To create one, run the Create a Sync Gateway Database request from the Sync Gateway 3.0 TravelSample Admin API collection as shown below in the screenshot animation.

Once the Sync Gateway database is created, you can run other operations on the database like creating a sync function, setting import filters, etc.

Creating a Sync Gateway user

Before you can start interacting with the Sync Gateway database via the public REST endpoint, you will have to create a sync gateway user. For this, run the Create a new user request from the Sync Gateway 3.0 TravelSample Admin API collection as shown below. This will create a user named demo with the password of password. Once a user is created, you can use the public REST endpoint to interact with the database.

Data Access

Accessing documents in the database and modifying them can be done via either the admin REST API or the public REST API. In this example, we use the public interface. All requests are executed using the {{username}} user that was created via the Create a new user request discussed earlier. Use the password of password for requests.

The travel-sample bucket is preloaded with sample data. So you can retrieve any document in the sample bucket using the Get Document request from the Sync Gateway 3.0 TravelSample Public API collection. Replace newdoc with doc in the request to retrieve an existing document from the bucket.

You can create a new document and edit it by running requests from the Sync Gateway 3.0 TravelSample Public API collection as shown below.

Monitoring

Finally, you can monitor Sync Gateway by running the Debugging/monitoring runtime stats in Prometheus format request from the Sync Gateway 3.0 TravelSample Metrics API as shown below.

Next Steps

Familiarize yourself with the other REST APIs by running through the other requests and customizing the requests as needed.

The Postman collections in this repo are shared as a convenience for administrators and developers to get started with Sync Gateway. It is not officially supported by Couchbase and as such, there are no guarantees that the Collections will remain up-to-date with the evolution of the REST API. To that end, contributions to keep the collections up-to-date are welcome! 

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.

Acknowledgements

I would like to thank Isaac Lambat, Engineer on the Sync Gateway team, for his input on this blog post.

Resources

• Postman API client website
• Postman files on Github for Couchbase Sync Gateway
• Couchbase Travel Sample documentation
• Docker download site
• Get started on Couchbase Capella – in the cloud, with a free trial (no credit card required)