How to use Cosmos DB REST API with Postman in 2021

Josué Martínez Buenrrostro — Mon, 23 Aug 2021 21:26:28 +0000

Introduction

Using Cosmos DB REST API from Postman can be a challenge.
It involves send some mandatory request headers, mainly for authorization porpoises.

You can give it a look at:
https://docs.microsoft.com/en-us/rest/api/cosmos-db/access-control-on-cosmosdb-resources
As well as a C# Sample at: https://github.com/Azure/azure-cosmos-dotnet-v2/tree/master/samples/rest-from-.net

This post help you to make it easier.

What do you need?

An Azure Cosmos DB Account: If you don't already have one, you can get it from free: https://docs.microsoft.com/en-us/azure/cosmos-db/free-tier.
Last version of Postman installed: To install it, look at: https://learning.postman.com/docs/getting-started/installation-and-updates/. You can use web app version instead: https://learning.postman.com/docs/getting-started/installation-and-updates/.

How to do it?

To make process simple in Postman, we will be creating one collection with necessary collection variables and a pre-request script to fill those variables before sending the request to the server, then in each request, we will be filling those variables with the corresponding variable values.

Disclaimer

This is not a post oriented to learn Postman, then just expect to get general guidance instead of detailed steps, then I am putting the Postman documentation link into each step. Feel free to click on the links to see how to do it. Remember that you always can look at Postman docs page.

The process consist on the next steps:

Next we are going to see each step in a detailed way.

Get Cosmos DB URI and KEY

You can go to the Azure Portal, then click on your Cosmos BD account, and then go to the "🔑Keys" option into the "Settings" section and get: "URI" and either "PRIMARY KEY" or "SECONDARY KEY" (if you will be doing just read only operation it is preferable to use data from "Read-only Keys" tab.

If you feel more comfortable using a shell, then you can get them using either Powershell or az.

Create a new Postman Collection

In this post, we are assuming that collection name will be "Cosmos DB REST".
See hot to do it in: https://learning.postman.com/docs/sending-requests/intro-to-collections/#creating-collections

Create Postman Collection variables

See how to do it in: https://learning.postman.com/docs/sending-requests/variables/#defining-collection-variables).
An then create next variables:

VARIABLE	CURRENT VALUE	NOTES
authorization_type	master	We are using Master Key Authorization but we can use a different option.
authorization_version	1.0	See valid values.
authorization_signature	PRIMARY KEY value obtained in step Get Cosmos DB URI and KEY.	See valid values.
x-ms-version	2018-12-31	See supported REST API Versions.

Example:

Important: We prefer to set just "CURRENT VALUE" for each variable. Check why at Adding environment variables Postman documentation.

Create pre-request scripts

See what is it at: https://learning.postman.com/docs/writing-scripts/pre-request-scripts/
The next pre-request script will test for mandatory variables, calculate and set valid headers for all the request in the collection.
To see how to create a pre-request script in Postman see: https://learning.postman.com/docs/writing-scripts/pre-request-scripts/#scripting-before-your-request-runs.
To see GitHub Gist of the pre-request script go to: https://gist.github.com/josuemb/f03232ac043dfa0ff645a367c69383e8
GitHub Gist:

Example:

Add a new request to the collection

See how to do it in: https://learning.postman.com/docs/sending-requests/intro-to-collections/#adding-requests
Since we are already creating all needed request headers in the pre-request script (see step 4), then we just need to create a new request by indicating: verb, uri, body (optional) as well as additional request headers (just in case you need it).
Example:
Now we will create a new request to get the list the databases for a given Cosmos DB Account. To create it we will need:

Cosmos DB URI: We already have seen how to get it in step 1. In this case it is: https://jmbcosmosnotebookdemo.documents.azure.com:443/ but we can abbreviate it as: https://jmbcosmosnotebookdemo.documents.azure.com/ since 443 is the standard port for https protocol.
List Databases URI: In this case: https://jmbcosmosnotebookdemo.documents.azure.com/dbs. To see other operations, see: https://docs.microsoft.com/en-us/rest/api/cosmos-db/common-tasks-using-the-cosmosdb-rest-api and to see valid URIs see: https://docs.microsoft.com/en-us/rest/api/cosmos-db/cosmosdb-resource-uri-syntax-for-rest That's it. Then we can execute the request and see response. Example:

Summary

Once you have done all previous steps, you can create any request and all needed request headers will be added automatically and you just need to add elements specific to each request.
Get a Postman Collection example from: https://www.getpostman.com/collections/57e0af5bf2d7021d4d15
And then you can import it as is documented on: https://learning.postman.com/docs/running-collections/working-with-data-files/
Feel free to reach me in twitter: @josuemb

DEV Community: Josué Martínez Buenrrostro