Couchbase Sync Gateway supports a RESTful interface that allows web based clients to administer, monitor and interact with the Sync Gateway. With the 3.0 release, Sync Gateway database admistration is handled exclusively via the admin REST endpoint.
This repo contains Postman Collections and environment variable definition file corresponding to v3.0 of Sync Gateway REST Interface. Think of a Postman Collection as a group of saved requests, organized in folders and subfolders. You can use the collections as a starting point and customize it per your environment. Then, use the Postman API client to send reqests to the Sync Gateway and to inspect responses. Only RBAC users with the right roles and privileges can excute the requests.
In addition, the repo also contains a TravelSample folder that contains a custom collection for a Travel Sample application. More details on that follow.
Disclaimer: 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.
The collection supports v3.0 of Sync Gateway REST interface.
Sync-Gateway-3.0-Admin-API.postman_collection corresponds to the Sync Gateway Admin interface that includes database management and administration, defining access controls and end user management.
Sync-Gateway-3.0-Public-API.postman_collection corresponds to the Sync Gateway Public interface that enables read/write access to application data.
Sync-Gateway-3.0-Metrics-API.postman_collection corresponds to the Sync Gateway Metrics interface that enables access to cluster-level stats in Prometheus and custom JSON format.
Sync-Gateway-3.0-Environment.postman_environment is the Environment Definitions file that defines the variables. The variables will have to be customized with values corresponding to your environment.
-
Download Postman client for free for your platform. There is a Pro version as well if you want the added functionality.
-
Launch Postman API client and import the collections and environment file
-
Update the environment file settings per your environment and start executing requests against your Sync Gateway
We have put together a custom version of the Postman collections corresponding to Travel Sample Application. These are located in the "travel-sample" folder of the repo.
Some notable differences from the main collections -
Tests Most of the requests in the collections include some simple tests to verify if the request was succesful or not.
Request Chaining Collections also support 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.
So for instance,
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. The test associated with the request extracts the “_rev” value and sets the “rev” environment variable
-
Download Postman client for free for your platform. There is a Pro version as well if you want the added functionality.
-
Docker must be installed on your laptop. On Windows, you may need admin privileges. Ensure that you have sufficient memory and cores allocated to docker. At Least 3GB of RAM is recommended.
-
Sync-Gateway-3.0-TravelSample-Admin-API.postman_collection.json: Collection of requests to create Sync Gateway travel-sample database, to configure and to manage the database and to create Sync Gateway users. All requests in this collection have to be authenticated .
-
Sync-Gateway-3.0-TravelSample-Public-API.postman_collection.json: Collection of requests to create, update and access documents from travel-sample database. All requests in this collection have to be authenticated.
-
Sync-Gateway-3.0-TravelSample-Metrics-API.postman_collection.json: Collection of requests to create, update and access documents from travel-sample database. All requests in this collection have to be authenticated.
To be able to run the collection, you need an enviroment with Couchbase Server and Sync Gateway. Running it in docker containers is the simplest option. We have pre-built images that has everything configured and good to go.
- Create a docker network named “workshop”
docker network ls
docker network create -d bridge workshopWe have a custom docker imagepriyacouch/couchbase-server-travelsample:7.x-dev of couchbase server. This image
(a) Loads the travel-sample bucket
(b) Configures three RBAC users -
- "admin" user is the user credentials with which the Sync Gateway connects to Couchbase Server
- "sgw-cluster" user which is used for cluster-level operations via the Sync Gateway admin/metrics REST endpoint
- "sgw-admin" user which is used for sync gateway database-level administrative operations via the Sync Gateway admin/metrics REST endpoint
docker stop cb-server
docker rm cb-server
docker run -d --name cb-server --network workshop -p 8091-8094:8091-8094 -p 11210:11210 priyacouch/couchbase-server-travelsample:7.x-dev
- The server would take a few minutes to deploy and get fully initialized. So be patient.
docker logs -f cb-server- You should see the following once setup is completed
100 50 0 0 100 50 0 4166 --:--:-- --:--:-- --:--:-- 4545
* Closing connection 0
SUCCESS: Bucket created
SUCCESS: User admin set
/entrypoint.sh couchbase-server-
Then open up http://localhost:8091 in browser Sign in as “Administrator” and “password” in login page
-
Go to “buckets” menu and confirm that the
travel-samplebucket is loaded. This bucket contains sample data. -
Go to “security” menu and confirm the following users are created. The users have been explained earlier.
-
Sync Gateway needs to be bootstrapped with a startup configuration file. The sync-gateway-config-travelsample-bootstrap.json file is available in the sample "travel-sample" folder.
-
Download the configuration file. Switch to the the folder which contains the downloaded json file and run the following commands
cd /path/to/cloned/repo/travel-sample- Follow these instructions to deploy Sync Gateway with the downloaded config file
docker stop sync-gateway
docker rm sync-gateway- Windows Systems:
docker run -p 4984-4986:4984-4986 --network workshop --name sync-gateway -d -v %cd%/ync-gateway-config-travelsample-bootstrap.json:/etc/sync_gateway/sync_gateway.json couchbase/sync-gateway:3.0.0-beta02-enterprise /etc/sync_gateway/sync_gateway.json- Non-Windows Systems:
docker run -p 4984-4986:4984-4986 --network workshop --name sync-gateway -d -v `pwd`/ync-gateway-config-travelsample-bootstrap.json:/etc/sync_gateway/sync_gateway.json couchbase/sync-gateway:3.0.0-beta02-enterprise /etc/sync_gateway/sync_gateway.json- You can confirm that the Sync Gateway is up and running by verifying the log messages
docker logs -f sync-gatewayYou will see bunch of log messages. Make sure no errors
- Then open up http://localhost:4984 in browser You should see equivalent of the following message
{"couchdb":"Welcome","vendor":{"name":"Couchbase Sync Gateway","version":"3.0"},"version":"Couchbase Sync Gateway/{version-maintenance}(145;e3f46be) EE"}-
Launch Postman API client and import all the three "travelsample" collections and the corresponding
Sync-Gateway-3.0-TravelSample-Environment.postman_environmentenvironment file. The environmental file has been customized for the travel-sample applicatin. Spend some time exploring the same. -
All the requests are setup to use the relevant user for authorization. However, you will need to provide password. All the users are setup with a password of "password". So make sure you configure the "Authorization header" of your requests.
- First, lets do a sanity test. For that run the "Get Sync Gateway Info" request from the Admin API collection. You should see details of the Sync Gateway in the response.
Depending on whether the request is a cluster-level request or a database-level request, the user specified in the Authorization header may be "{{clusteradmin}}" or "{{dbadmin}}" respectively. Use password of "password" for requests.
- Starting v3.0, all sync gateway database administration including database creation is handled via the admin REST endpoint. So this means that you would need to first create a sync gateway database. For this run the "Create a Sync Gateway Database" request from the "Sync Gateway 3.0 TravelSample Admin API" collection as shown below. Once database is created, you can run other operations on the database like creating a sync function, setting import filters etc.
- 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 password of "password". Once user is created, you can use the public REST endpoint to interact with the database.
Accessing documents in the database and modifying it can be done via the either the admin REST API or the public REST API. In this example, we will use the pubic interface. All requests are executed using "{{username}}" user that was created via the "Create a new user" request discussed earlier. Use password of "password" for requests.
-
The travel-sample bucket is preloaded with sample data. You can retrieve that 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 bucket.
-
You can also create a new document and edit it by running requests from the "Sync Gateway 3.0 TravelSample Public API" collection as shown below.
- Finally, you can monitor the 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.
Familiarize yourself with the other REST APIs in the travel-sample collections by running through the other requests and customizing the requests as needed.Bug fix and enhancement contributions welcome.