Important Update: Please note that the V3 API will be deprecated soon and will no longer receive updates or support beyond its end-of-life date. To benefit from enhanced features and improved performance, we strongly recommend transitioning to our new V4 API. We’ve prepared a comprehensive guide detailing the steps on how to start working with V4 to make the process as smooth as possible for you.
Couchbase Capella offers a public API which enables administrators and developers to integrate and interact with the Control Plane using a variety of programming languages and platforms. The RESTful APIs are intended to enable customers to integrate with Couchbase Capella and perform operations such as:
-
- Onboarding and offboarding users
- Managing the lifecycle of a database
- Monitoring a database
This blog post will show you how to utilize the Postman API client to interact with the Couchbase Capella Public API through the REST interface.
Note that this tutorial uses v3 of the Capella Public API. A revamped version of the API is in the works that may introduce some breaking changes. As such, we discourage you to use this version of the API in production deployments as we do not make guarantees on backwards compatibility with this version. However, we encourage you to evaluate the API and invite feedback on capabilities you would like to see in the new version of public API.
Prerequisites
-
- Postman is a great tool to interact with a REST API. In the remainder of this tutorial I assume you have installed Postman locally and it is ready for use. You can download it from postman.com/downloads
- The next step is to download Couchbase Capella’s OpenAPI file from the Capella documentation website.
-
- You will also need to create an access key and a secret key to use the Public API. See instructions on how to set up your keys here.
Create a new Postman environment
In this step you will set up a new Postman environment (a set of variables you can use in your Postman requests). Couchbase Capella’s Public API will require your access and secret keys.
Make sure you name the variables exactly as follows:
-
- accessKey containing your access key
- secretKey containing your secret
It is probably best to set this new environment as the active one.
Import the OpenAPI definition
The next step is to import the OpenAPI definition file that you downloaded earlier. This will create a new Postman collection.
At this point, you have the collection and environment set up in Postman.
Configure Authentication
The Couchbase Capella Public API uses a Bearer token mechanism for authentication; each call to the Public API must be authenticated. You can find details on the two headers you must send with every request by consulting the official documentation on security headers.
To help you get started, we have a Postman pre-request script that generates the necessary headers based on your access and secret keys.
You must copy and paste this code into the Pre-request Script section of the collection. You can find more information about Pre-request scripts by visiting Postman’s documentation website.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
// Grab the current endpoint infro from the request const url = pm.request.url.getPathWithQuery() // Grab the method from the request const method = pm.request.method; // Create a timestamp const now = new Date().getTime(); // Datetime in the past const yesterday = new Date(); yesterday.setDate(yesterday.getDate() - 1); // SHA-256 hash const createHash = (payload, secret) => { return CryptoJS.HmacSHA256(payload, secret) .toString(CryptoJS.enc.Base64); } // Create the bearerToken const setToken = (accessKey, hash) => { pm.environment.set("bearerToken", accessKey + ':' + hash); } // Create the Timestamp header const setTimestampheader = (date) => { pm.request.headers.add({ key: "Couchbase-Timestamp", value: date }); } // If accessKey and secretKey are defined, we can generate the hash if (pm.environment.has("accessKey") && pm.environment.has("secretKey")) { // Replace variables in the URL const parsedURL = pm.variables.replaceIn(url); // Generate the payload const payload = [method, parsedURL, now].join("\n"); console.log("Payload", payload); // Generate the hash const hash = createHash(payload, pm.environment.get("secretKey")) // Save the token to an env variable setToken(pm.environment.get("accessKey"), hash); // Add the timestamp header to the request setTimestampheader(now); } pm.environment.set("yesterday", yesterday.toJSON()); pm.environment.set("now", new Date().toJSON()); |
At this point you are ready to run your queries. Next we will look at how to run some of the Public API queries.
Run queries
As a first example, let’s run the List Users call in the users folder.
When you run this query, you will notice that the response is empty despite the fact that you have users in your system. This is because the query parameters were assigned default values that are incorrect.
You must amend the following query parameters: page and perPage. In the following example, I will change the page to 1 and the perPage to 100 to get the expected result from the API.
That is it! Now you are ready to discover Couchbase Capella’s Public API. I hope you find some interesting ways to use it in your project.
English