Azure Cosmos DB Operations (Rest API) with Postman

The process consist on the next steps:

1. Get Cosmos DB URI and KEY.
2. Create a new Postman Collection.
3. Create Postman Collection variables.

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

Step1

Create azure cosmos DB Account

Choose azure cosmos for NOSQL.

Step 2

Download simple document dB Microsoft postman.

Document link blow Here

GitHub – Aionsphere/cosmosdb-postman-collection: Postman collection demonstrating REST access for DocumentDB

After Download extra file

Step 3

How to Import file to Postman

Step 4

Select folder import files here.

Step 5

One other thing you need to setup is the environment variable as you see we are using some of the configured variables in the script, you can create a new environment variable using Postman by navigating to environments and add new environment with configured variables

Step 6

once you create the Cosmos DB account on Azure and navigate to the keys section on the left pane. You will see two types of tabs on the Keys. There are two types of keys, one type of users having the Key can Read and Write. Other type of users having the key can only Read.

Let’s understand different terms used while making a connection to Cosmos DB

Master Keys are keys are created when the Cosmos DB Account is created. This key can be regenerated by clicking on refresh icon to regenerate them in the Azure portal. When you are using Cosmos DB emulator you won’t be able to generate it. These keys are very sensitive ones and provide access to the administrative resources. We should be very careful when weneed to store them. Recommended way is to use Read-Only Keys as much as we can.

Resource Tokens are responsible for providing access to specific containers, documents, attachments, stored procedures, triggers, and UDFs. Each user must have a resource token. It is mandatory that every application needs to use a resource token to call Cosmos DB API.

Users are specific for Cosmos DB databases. You can attach specific permissions or roles to each user like the way we do in SQL server

Cosmos DB API

As i mentioned earlier we have many options to access to CosmosDB. Rest API is one of these options and it is the low level access way to Cosmos DB. Most of the features supported with SDK are available and you can customize all options of CosmosDB by using REST API. To customize the calls, and pass the required authorization information, you need to use http headers.

In the following example, I am going to try to create a database in CosmosDB emulator by using the REST API. First let’s look at the required header fields for this request. These requirement applies to all other REST API calls too.

x-ms-version : As the name indicates this is the version of the REST API. You can find the available versions here. If you are confused on what to use always use the latest one.

x-MS-date : This is the date of your request. It must be formatted by Coordinated Universal Time. (ex: Sun, 18 Jan 2024 05:00:23 GMT)

x-ms-session-token: It is required if you want to use session consistency. For each of your new write request in Session consistency, CosmosDB assings a new SessionToken to the calls. You need to track the right session token and use it in this header property to keep usng the same session. SDK does this for you in the background, if you want to use the REST API, you need to do this manually.

Authorization: This one is the most important and tricky one. This needs to get generated for each of your call to Cosmos DB. It must be in the following format

How to Call APIs with Postman:

To call Cosmos DB directly from POSTMAN, you need to get the Cosmosdb account URL we need to use. I will be using the account created in Azure protal

we need to look at the documentation of CosmosDB Rest API. You can find all URL locations from this link. Since I am trying to list the databases inside a collection, I am going to use the following path.

https://postmandemo.documents.azure.com:443/

Step 7

As we are requesting to get the list of databases, we are ready to add values to headers section. Click on Headers link, and add the following headers. These are the required HTTP headers for all CosmosDB REST API calls.

x-ms-version : 2019-06-30
(This is the latest version. You can find the other versions here.)

x-ms-date : {{utcDate}}
(This is the parameter we just created in POSTMAN Environment. We are going to generate its value in script.)

authorization : {{authToken}}
(This is the other parameter we just created. We are going to generate its value in script.)

Accept : application/json.
(This is required since this is going to be a GET Http Action.)

Your screen should looks like this

We are done with all the things needed to get the list of databases. Click on the send button to see the list of databases as response

Great! Look at all that information we received back in the body of the Response.

This is the way to test Cosmos DB API with POSTMAN. You can try different APIs with the simple collection we’ve created here. Now it becomes easy for developers to leverage the Cosmos DB api and to play around with it.

Successful send azure cosmos DB