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:
- Get Cosmos DB URI and KEY.
- Create a new Postman Collection.
- Create Postman Collection variables.
- Create pre-request script.
- Add a new request to the collection.
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
Oldest comments (3)
Is not it the same? sajeetharan.com/2019/07/01/easily-...
It is similar but I simplified needed variables and changed the algorithm since the post you are referring did nor work for some cases.
Thanks for the guide, really useful!
A question please. If i follow the steps, and run the postman collection, i get the error - TypeError: Cannot read properties of null (reading '1')
But if I copy the Pre-request Script from the collection into the Request's pre-request script part, then it works!
Where could i be going wrong?