How to use Cosmos DB REST API with Postman in 2021
Tags: azure, cosmosdb, postman, rest
Published: 2021-08-23 21:26:28

## Introduction <a name="Introduction">
Using [Cosmos DB REST API](https://docs.microsoft.com/en-us/rest/api/cosmos-db/) from [Postman](https://www.postman.com/) can be a challenge.
It involves send some mandatory [request headers](https://docs.microsoft.com/en-us/rest/api/cosmos-db/common-cosmosdb-rest-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? <a name="What-Do-You-Need">
1. **An [Azure Cosmos DB Account](https://docs.microsoft.com/en-us/azure/cosmos-db/introduction):**
If you don't already have one, you can get it from free: https://docs.microsoft.com/en-us/azure/cosmos-db/free-tier.
1. **Last version of [Postman](https://www.postman.com/) 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? <a name="How-To-Do-It">

To make process simple in Postman, we will be creating one collection with necessary [collection variables](https://learning.postman.com/docs/sending-requests/variables/#defining-collection-variables) and a [pre-request script](https://learning.postman.com/docs/writing-scripts/pre-request-scripts/) 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 <a name="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](https://learning.postman.com/docs/).

The process consist on the next steps:
1. Get Cosmos DB URI and KEY.
1. Create a new [Postman Collection](https://learning.postman.com/docs/sending-requests/intro-to-collections/#creating-collections).
1. Create [Postman Collection variables](https://learning.postman.com/docs/sending-requests/variables/#defining-collection-variables).
1. Create [pre-request script](https://learning.postman.com/docs/writing-scripts/pre-request-scripts/).
1. [Add a new request to the collection](https://learning.postman.com/docs/sending-requests/intro-to-collections/#adding-requests).

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

### Get Cosmos DB URI and KEY <a name="Get-CosmosDB-Uri-And-Key">
You can go to the [Azure Portal](https://portal.azure.com/), 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.
![Getting URI and KEY from Azure Portal](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ywquq72iocix1actsnie.jpg)
If you feel more comfortable using a shell, then you can get them using either [Powershell](https://docs.microsoft.com/en-us/azure/cosmos-db/scripts/powershell/common/keys-connection-strings) or [az](https://docs.microsoft.com/en-us/cli/azure/cosmosdb/keys?view=azure-cli-latest).

### Create a new Postman Collection <a name="Create-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 <a name="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](https://docs.microsoft.com/en-us/rest/api/cosmos-db/access-control-on-cosmosdb-resources?redirectedfrom=MSDN#authorization-header). |
| authorization_version | 1.0 | See [valid values](https://docs.microsoft.com/en-us/rest/api/cosmos-db/access-control-on-cosmosdb-resources?redirectedfrom=MSDN#authorization-header). |
| authorization_signature | PRIMARY KEY value obtained in step <a href="#Get-CosmosDB-Uri-And-Key">Get Cosmos DB URI and KEY</a>. | See [valid values](https://docs.microsoft.com/en-us/rest/api/cosmos-db/access-control-on-cosmosdb-resources?redirectedfrom=MSDN#authorization-header). |
| x-ms-version | 2018-12-31 | See [supported REST API Versions](https://docs.microsoft.com/en-us/rest/api/cosmos-db/#supported-rest-api-versions). |
**Example:**
![Collection Variables Example](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vhbzu197kio9wj9qj6f5.jpg)
**Important:** We prefer to set just "CURRENT VALUE" for each variable. Check why at [Adding environment variables](https://learning.postman.com/docs/sending-requests/managing-environments/#adding-environment-variables) Postman documentation.

### Create pre-request scripts <a name="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:**
{% gist https://gist.github.com/josuemb/f03232ac043dfa0ff645a367c69383e8 %}
**Example:**
![Pre-request Script Example](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/6sxxb3bz0gku4ay3jq7a.jpg)

### Add a new request to the collection <a name="Add-New-Request-To-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](https://learning.postman.com/docs/writing-scripts/pre-request-scripts/) (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](https://docs.microsoft.com/en-us/rest/api/cosmos-db/list-databases#request):** 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:**
![List Databases Example](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/cb6ifjfobo41v60cmt31.jpg)

## 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](https://twitter.com/josuemb)