Let's look at an example of testing an API consumption using Postman. However, there are other tools that can be used for consuming and testing our APIs.

Example:

  1. Open the Postman application on your desktop or go to the Postman web portal.
  2. Login into your Postman account.
  3. Create a new request within Postman.
  4. Select the operation method you wish to test from the available method dropdown list. This will depend on the operation method available for that API with the endpoint. In this example, it is the 'GET' method. And you can confirm is it available for that API by reviewing the Operations section of the API's definition page within Find and Use an API.
  5. Copy the Base URL from the API's Overview and details page within the Environments section within the Find and Use an API Consumption Portal.
  6. Paste that Base URL into the Request box within Postman.
  7. Go back to the API's Overview and details page within the Operations section within the Find and Use an API.
  8. Copy the URL template value. For example, '/info'. This represents the operation you are about to test using the GET method.
  9. Paste that URL template value into the Request box in Postman - appended to the end of the Base URL string you already have in Request box.
  10. Select the Send button to submit the request, so you can receive a response. Ensure you have provided the Subscription key. If the API has OAuth Application-flow, then you will also need to add the OAuth details including OAuth Client ID, Primary key (Secret) and OAuth Scope to the request before sending. Otherwise, you will receive an access denied or authorisation error.

You can add the Subscription key to the request in two ways:

The First - As a query parameter through the Query parameter name value (subscription-key) obtained from the API's Subscriptions detail page and Subscription key section within Find and Use an API.

You add the Subscription key to a request through the Query parameter by following these steps:

  1. Select the Params tab from your new Request in Postman.
  2. Go to the API's Subscriptions detail page and Subscription key section within Find and Use an API.
  3. Copy the Query parameter name value. For this example, the value is 'subscription-key'.
  4. Paste that value into the Query Params's Key field in Postman.
  5. Go back to the API's Subscriptions detail page and Subscription key section within Find and Use an API.
  6. Copy the Primary key value (select View link to reveal). It should look something like '01524318b2b948d0a58ef565947289fc'.
  7. Paste that 'Primary key' value into the Query Params's Value field in Postman.

The Second - As a header parameter through the 'Header name parameter value' (Apim-Subscription-Key) obtained from the API's Subscriptions detail page and Subscription key section.

You add the Subscription key to a request through the Header parameter by following these steps:

  1. Select the Headers tab from your new Request in Postman.
  2. Go to the API's Subscriptions detail page and Subscription key section within Find and Use an API.
  3. Copy the Header name value. For this example, the value is 'Apim-Subscription-Key'.
  4. Paste that value into the Headers Key field in Postman.
  5. Go back to the API's Subscriptions detail page and Subscription key section Find and Use an API.
  6. Copy the Primary key value (click View link to reveal). It should look something like '01524318b2b948d0a58ef565947289fc'
  7. Paste that Primary key value into the Header's Value field in Postman.

If the API Subscription also has a Native OAuth Application-flow, then you will need to obtain a token.

You can obtain a token for your API Subscription by following these steps:

  1. Select the POST method from the available operation's method dropdown list for the new request in Postman.
  2. Go to the API's Subscriptions detail page and Native OAuth Application-flow section within Find and Use an API.
  3. Copy the OAuth token endpoint value. For this example, the value is 'https://login.microsoftonline.com/7d85e51f-c73e-40a8-a5c5-4c3b41de8eb9/oauth2/v2.0/token'. This will be a URL given by the token Business-to-Consumer (B-2-C) provider.
  4. Paste that URL into the new Request box within Postman.
  5. Select the Body tab for your new Request in Postman. You will be presented with all the Key and Value fields requiring inputs.
  6. Go to the API's Subscriptions detail page and Native OAuth Application-flow section within Find and Use an API.
  7. Copy the 'OAuth Client ID' value.
  8. Paste it into the Value field for client_id Key field within the Body tab in Postman.
  9. Check the Value field for grant_type Key field is set to client_credentials within the Body tab in Postman.
  10. Go to the API's Subscriptions detail page and Native OAuth Application-flow section withinFind and Use an API.
  11. Copy the Primary key value.
  12. Paste it into the Value field for 'client_secret' Key field within the Body tab in Postman.
  13. Go to the API's Subscriptions detail page and Native OAuth Application-flow section within Find and Use an API.
  14. Copy the 'OAuth Scope' value.
  15. Paste it into the Value field for scope Key field within the Body tab in Postman.
  16. Select the 'Send button to submit the request to the token provider. You will get a token back as a response. This token can be viewed within the Response Body below in the access_token field value.
  17. Go to the Response Body (JSON format) for your submitted request in Postman.
  18. Find the field access_token.
  19. Copy this access_token value. It will look something like 'MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3'
  20. Go back to your request in Postman.
  21. Select the Authorisation tab for your new Request in Postman.
  22. Go to the Type dropdown option, select 'Bearer token' for type.
  23. Paste the access_token value you copied to the Token text box presented to you in Postman.
  24. Select the Send button again, to submit the request with the 'Bearer token' now added. This will return a response for the API that can be viewed within the response body in Postman. The response will contain various fields and values including headers, any query parameters, response message and timestamp in JSON format within Postman. You can download the JSON response file.