Create a Postman collection for a custom connector

Postman is an app for making HTTP requests, and Postman collections help you organize and group related API requests. Collections can make custom connector development faster and easier if you don't already have an OpenAPI definition for your API. For more information about collections, see Creating collections in the Postman documentation.

In this topic, you create a collection that includes a request and response from the Cognitive Services Text Analytics API. In a related topic, you create a connector using this collection.

Prerequisites

• The Postman app
• An API key for the Cognitive Services Text Analytics API

Create an HTTP request for the API

1. In Postman, on the Builder tab, select the HTTP method, enter the request URL for the API endpoint, and select an authorization protocol, if any.

   

   Parameter	Value
   HTTP method	"POST"
   Request URL	"https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment"
   Authorization	"No Auth" (you specify an API key in the next step)

2. Enter key-value pairs for the request header. For common HTTP headers, you can select from the dropdown list.

   

   Key	Value
   Ocp-Apim-Subscription-Key	your-API-subscription-key, which you can find in your Cognitive Services account
   Content-Type	"application/json"

3. Enter content that you want to send in the request body. To check that the request works by getting a response back, choose Send.

   

   {
       "documents": [{
           "language": "en-us",
           "id": "1", 
           "text": "I enjoyed the new movie after a long day."
       }]
   }
   

   The response field contains the full response from the API, including the result or an error, if any occurred.

   

For more information about HTTP requests, see Requests in the Postman documentation.

Save the collection

1. Choose Save.

   

2. Under Save Request, provide a request name and a request description. The custom connector uses these values for the API operation summary and description.

   

   Parameter	Value
   Request name	"DetectSentiment"
   Request description	"The API returns a numeric score between 0 and 1. Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment."

3. Choose + Create Collection and provide a collection name. The custom connector uses this value when you call the API. Choose the check mark, which creates a collection folder, then choose Save to SentimentDemo.

   

   Parameter	Value
   Collection name	"SentimentDemo"

Save the request response

Now you've saved your request, you can save the response. That way, the response appears as an example when you load the request later.

1. Above the response window, choose Save Response.

   

   Custom connectors support only one response per request. If you save multiple responses per request, only the first one is used.

2. At the top of the app, provide a name for your example response, and choose Save Example.

   

If your API had additional features, you would continue to build your Postman collection with any additional requests and responses.

Export the Postman collection

You now export the collection as a JSON file, which you import using the custom connector wizard. Before you export the collection, remove the content type and security headers—these were required to make API requests, but they are handled differently in the custom connector.

1. Under Headers, hover over each header, and choose the X next to the header to remove it. Choose Save to save the collection again.

   

2. Choose the ellipsis (. . . .) next to the collection, then choose Export.

   

3. Choose the Collection v1 export format, choose Export, then browse to the location where you want to save the JSON file.

   

   Note

   Currently, you can use only v1 collections for custom connectors.

Next steps

You're now ready to define a custom connector based on the Postman collection you created:

• Create a custom connector from a Postman collection