How to use Postman to send requests to the Azure Digital Twins APIs

Postman is a REST testing tool that provides key HTTP request functionalities in a desktop and plugin-based GUI. You can use it to craft HTTP requests and submit them to the Azure Digital Twins REST APIs.

This article describes how to configure the Postman REST client to interact with the Azure Digital Twins APIs, through the following steps:

  1. Use the Azure CLI to get a bearer token that you will use to make API requests in Postman.
  2. Set up a Postman collection and configure the Postman REST client to use your bearer token to authenticate. When setting up the collection, you can choose either of these options:
    1. Import a pre-built collection of Azure Digital Twins API requests.
    2. Create your own collection from scratch.
  3. Add requests to your configured collection and send them to the Azure Digital Twins APIs.

Azure Digital Twins has two sets of APIs that you can work with: data plane and control plane. For more about the difference between these API sets, see Azure Digital Twins APIs and SDKs. This article contains information for both API sets.

Prerequisites

To proceed with using Postman to access the Azure Digital Twins APIs, you need to set up an Azure Digital Twins instance and download Postman. The rest of this section walks you through these steps.

Set up Azure Digital Twins instance

To work with Azure Digital Twins in this article, you first need to set up an Azure Digital Twins instance. You also need the required permissions for using it. If you already have an Azure Digital Twins instance set up, you can use it instead.

Otherwise, follow the instructions in Set up an instance and authentication. The instructions contain information to help you verify that you've completed each step successfully.

After you set up your instance, make a note of the following values. You'll need these values to connect to the instance later:

  • The instance's host name. You can find the host name in the Azure portal.
  • The Azure subscription that you used to create the instance. Either its name or its ID will work. You can find the subscription on your instance's Overview page in the Azure portal.

Download Postman

Next, download the desktop version of the Postman client.

Get bearer token

Now that you've set up Postman and your Azure Digital Twins instance, you'll need to get a bearer token that Postman requests can use to authorize against the Azure Digital Twins APIs.

There are several possible ways to obtain this token. This article uses the Azure CLI to sign into your Azure account and obtain a token that way.

If you have an Azure CLI installed locally, you can start a command prompt on your machine to run the following commands. Otherwise, you can open an Azure Cloud Shell window in your browser and run the commands there.

  1. First, make sure you're logged into Azure with the appropriate credentials, by running this command:

    az login
    
  2. Next, use the az account get-access-token command to get a bearer token with access to the Azure Digital Twins service. In this command, you'll pass in the resource ID for the Azure Digital Twins service endpoint, in order to get an access token that can access Azure Digital Twins resources.

    The required context for the token depends on which set of APIs you're using, so use the tabs below to select between data plane and control plane APIs.

    To get a token to use with the data plane APIs, use the following static value for the token context: 0b07f429-9f4b-4714-9392-cc5e8e80c8b0. This is the resource ID for the Azure Digital Twins service endpoint.

    az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0
    

    Note

    If you need to access your Azure Digital Twins instance using a service principal or user account that belongs to a different Azure Active Directory tenant from the instance, you'll need to request a token from the Azure Digital Twins instance's "home" tenant. For more information on this process, see Write app authentication code.

  3. Copy the value of accessToken in the result, and save it to use in the next section. This is your token value that you will provide to Postman to authorize your requests.

    Screenshot of the console showing the result of the az account get-access-token command. The accessToken field and its sample value is highlighted.

Tip

This token is valid for at least five minutes and a maximum of 60 minutes. If you run out of time allotted for the current token, you can repeat the steps in this section to get a new one.

Next, you'll set up Postman to use this token to make API requests to Azure Digital Twins.

About Postman collections

Requests in Postman are saved in collections (groups of requests). When you create a collection to group your requests, you can apply common settings to many requests at once. This can greatly simplify authorization if you plan to create more than one request against the Azure Digital Twins APIs, as you only have to configure these details once for the entire collection.

When working with Azure Digital Twins, you can get started by importing a pre-built collection of all the Azure Digital Twins requests. You may want to do this if you're exploring the APIs and want to quickly set up a project with request examples.

Alternatively, you can also choose to start from scratch, by creating your own empty collection and populating it with individual requests that call only the APIs you need.

The following sections describe both of these processes. The rest of the article takes place in your local Postman application, so go ahead and open the Postman application on your computer now.

Import collection of Azure Digital Twins APIs

A quick way to get started with Azure Digital Twins in Postman is to import a pre-built collection of requests for the Azure Digital Twins APIs.

Download the collection file

The first step in importing the API set is to download a collection. Choose the tab below for your choice of data plane or control plane to see the pre-built collection options.

There are currently two Azure Digital Twins data plane collections available for you to choose from:

  • Azure Digital Twins Postman Collection: This collection provides a simple getting started experience for Azure Digital Twins in Postman. The requests include sample data, so you can run them with minimal edits required. Choose this collection if you want a digestible set of key API requests containing sample information.
    • To find the collection, navigate to the repo link and open the file named postman_collection.json.
  • Azure Digital Twins data plane Swagger: This repo contains the complete Swagger file for the Azure Digital Twins API set, which can be downloaded and imported to Postman as a collection. This will provide a comprehensive set of every API request, but with empty data bodies rather than sample data. Choose this collection if you want to have access to every API call and fill in all the data yourself.
    • To find the collection, navigate to the repo link and choose the folder for the latest spec version. From here, open the file called digitaltwins.json.

Here's how to download your chosen collection to your machine so that you can import it into Postman.

  1. Use the links above to open the collection file in GitHub in your browser.
  2. Select the Raw button to open the raw text of the file. Screenshot of the data plane digitaltwins.json file in GitHub. There is a highlight around the Raw button.
  3. Copy the text from the window, and paste it into a new file on your machine.
  4. Save the file with a .json extension (the file name can be whatever you want, as long as you can remember it to find the file later).

Import the collection

Next, import the collection into Postman.

  1. From the main Postman window, select the Import button. Screenshot of a newly opened Postman window. The 'Import' button is highlighted.

  2. In the Import window that follows, select Upload Files and navigate to the collection file on your machine that you created earlier. Select Open.

  3. Select the Import button to confirm.

    Screenshot of Postman's 'Import' window, showing the file to import as a collection and the Import button.

The newly imported collection can now be seen from your main Postman view, in the Collections tab.

Screenshot of the main Postman window. The newly imported collection is highlighted in the 'Collections' tab.

Next, continue on to the next section to add a bearer token to the collection for authorization and connect it to your Azure Digital twins instance.

Configure authorization

Next, edit the collection you've created to configure some access details. Highlight the collection you've created and select the View more actions icon to pull up a menu. Select Edit.

Screenshot of Postman. The 'View more actions' icon for the imported collection is highlighted, and 'Edit' is highlighted in the options.

Follow these steps to add a bearer token to the collection for authorization. This is where you'll use the token value you gathered in the Get bearer token section in order to use it for all API requests in your collection.

  1. In the edit dialog for your collection, make sure you're on the Authorization tab.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. Set the Type to OAuth 2.0, paste your access token into the Access Token box, and select Save.

    Screenshot of Postman edit dialog for the imported collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

Additional configuration

If you're making a data plane collection, help the collection connect easily to your Azure Digital Twins resources by setting some variables provided with the collections. When many requests in a collection require the same value (like the host name of your Azure Digital Twins instance), you can store the value in a variable that applies to every request in the collection. Both of the downloadable collections for Azure Digital Twins come with pre-created variables that you can set at the collection level.

  1. Still in the edit dialog for your collection, move to the Variables tab.

  2. Use your instance's host name from the Prerequisites section to set the CURRENT VALUE field of the relevant variable. Select Save.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Variables' tab. The 'CURRENT VALUE' field is highlighted.

  3. If your collection has additional variables, fill and save those values as well.

When you're finished with the above steps, you're done configuring the collection. You can close the editing tab for the collection if you want.

Explore requests

Next, explore the requests inside the Azure Digital Twins API collection. You can expand the collection to view the pre-created requests (sorted by category of operation).

Different requests require different information about your instance and its data. To see all the information required to craft a particular request, look up the request details in the Azure Digital Twins REST API reference documentation.

You can edit the details of a request in the Postman collection using these steps:

  1. Select it from the list to pull up its editable details.

  2. Fill in values for the variables listed in the Params tab under Path Variables.

    Screenshot of Postman. The collection is expanded to show a request. The 'Path Variables' section is highlighted in the request details.

  3. Provide any necessary Headers or Body details in the respective tabs.

Once all the required details are provided, you can run the request with the Send button.

You can also add your own requests to the collection, using the process described in the Add an individual request section below.

Create your own collection

Instead of importing the existing collection of all Azure Digital Twins APIs, you can also create your own collection from scratch. You can then populate it with individual requests using the Azure Digital Twins REST API reference documentation.

Create a Postman collection

  1. To create a collection, select the New button in the main postman window.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Choose a type of Collection.

    Screenshot of the 'Create New' dialog in Postman. The 'Collection' option is highlighted.

  2. This will open a tab for filling the details of the new collection. Select the Edit icon next to the collection's default name (New Collection) to replace it with your own choice of name.

    Screenshot of the new collection's edit dialog in Postman. The Edit icon next to the name 'New Collection' is highlighted.

Next, continue on to the next section to add a bearer token to the collection for authorization.

Configure authorization

Follow these steps to add a bearer token to the collection for authorization. This is where you'll use the token value you gathered in the Get bearer token section in order to use it for all API requests in your collection.

  1. Still in the edit dialog for your new collection, move to the Authorization tab.

    Screenshot of the new collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. Set the Type to OAuth 2.0, paste your access token into the Access Token box, and select Save.

    Screenshot of the Postman edit dialog for the new collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

When you're finished with the above steps, you're done configuring the collection. You can close the edit tab for the new collection if you want.

The new collection can be seen from your main Postman view, in the Collections tab.

Screenshot of the main Postman window. The newly created custom collection is highlighted in the 'Collections' tab.

Add an individual request

Now that your collection is set up, you can add your own requests to the Azure Digital Twin APIs.

  1. To create a request, use the New button again.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Choose a type of Request.

    Screenshot of the 'Create New' dialog in Postman. The 'Request' option is highlighted.

  2. This action opens the SAVE REQUEST window, where you can enter a name for your request, give it an optional description, and choose the collection that it's a part of. Fill in the details and save the request to the collection you created earlier.

    Screenshot of 'Save request' window in Postman showing the fields described. The 'Save to Azure Digital Twins collection' button is highlighted.

You can now view your request under the collection, and select it to pull up its editable details.

Screenshot of Postman. The Azure Digital Twins collection is expanded to show the request's details.

Set request details

To make a Postman request to one of the Azure Digital Twins APIs, you'll need the URL of the API and information about what details it requires. You can find this information in the Azure Digital Twins REST API reference documentation.

To proceed with an example query, this article will use the Query API (and its reference documentation) to query for all the digital twins in an instance.

  1. Get the request URL and type from the reference documentation. For the Query API, this is currently POST https://digitaltwins-host-name/query?api-version=2020-10-31.

  2. In Postman, set the type for the request and enter the request URL, filling in placeholders in the URL as required. This is where you will use your instance's host name from the Prerequisites section.

    Screenshot of the new request's details in Postman. The query URL from the reference documentation has been filled into the request URL box.

  3. Check that the parameters shown for the request in the Params tab match those described in the reference documentation. For this request in Postman, the api-version parameter was automatically filled when the request URL was entered in the previous step. For the Query API, this is the only required parameter, so this step is done.

  4. In the Authorization tab, set the Type to Inherit auth from parent. This indicates that this request will use the authorization you set up earlier for the entire collection.

  5. Check that the headers shown for the request in the Headers tab match those described in the reference documentation. For this request, several headers have been automatically filled. For the Query API, none of the header options are required, so this step is done.

  6. Check that the body shown for the request in the Body tab matches the needs described in the reference documentation. For the Query API, a JSON body is required to provide the query text. Here is an example body for this request that queries for all the digital twins in the instance:

    Screenshot of the new request's details in Postman, on the Body tab. It contains a raw JSON body with a query of 'SELECT * FROM DIGITALTWINS'.

    For more information about crafting Azure Digital Twins queries, see Query the twin graph.

  7. Check the reference documentation for any other fields that may be required for your type of request. For the Query API, all requirements have now been met in the Postman request, so this step is done.

  8. Use the Send button to send your completed request. Screenshot of Postman showing the details of the new request. The Send button is highlighted.

After sending the request, the response details will appear in the Postman window below the request. You can view the response's status code and any body text.

Screenshot of the sent request in Postman. Below the request details, the response is shown. Status is 200 OK and body shows query results.

You can also compare the response to the expected response data given in the reference documentation, to verify the result or learn more about any errors that arise.

Next steps

To learn more about the Digital Twins APIs, read Azure Digital Twins APIs and SDKs, or view the reference documentation for the REST APIs.