Jun 26, 2020Introducing Postman Collections for Contentstack APIs
We’re excited to announce the release of the Postman Collections for our Content Delivery, Content Management, and GraphQL APIs. These collections let you connect to your Contentstack accounts and try out our APIs.
This article introduces you to Postman and walks you through the process of testing Contentstack APIs using the newly-released Postman collections.
About Postman
Postman is a popular API client that lets you build and test APIs through its easy-to-use GUI. With Postman, it’s easy to write test cases, inspect responses, and do a lot more.
About Contentstack Postman collections
Contentstack Postman collection is a set of APIs that you can import and start using instantly. We have released collections for our Content Delivery, Content Management, and GraphQL APIs. These collections come with predefined environment variables to help you get started immediately.
The process to start using Contentstack Postman collections is relatively simple:
Download Latest Contentstack Postman Collections
Configure Environment Variables
Make an API Request in Postman
Update Your Postman Collection
Let’s look at them in detail.
Step 1 – Download Latest Contentstack Postman Collections
It is imperative to have the latest desktop version of Postman to use Contentstack Postman collections. After installing Postman, you can download the latest versions of the Postman collection.
To download and import the collection into your Postman app, click on the respective Run in Postman button:
Content Delivery API
Content Management API
GraphQL API
Note: For Windows, downloading the Content Management API collection doesn't download the environment automatically due to the larger size of the environment file. Consequently, Windows users need to download the Content Management API - Environment file manually and import it in their Postman environment.
These collections cover all the Content Delivery, Content Management, and GraphQL API endpoints for Contentstack.
You can even download the Postman collection from our GitHub page. You can follow the instructions given in the Postman collection Readme file for more details.
Step 2 – Configure Environment Variables
When you download and import the Postman collection, you download and import the related environment as well.
Set your Contentstack account-specific values for the required environment variable. If needed, you can add your own environment variables.
As the environment variables are referenced across multiple API requests, once you set the variables, it becomes more convenient to make repeated use of the Postman collection.
Adding Environment Variables
To add and set up your Postman environment variables, perform the following steps:
Identify the environment variable(s) that you want to define.
In Postman, click on the “Manage Environments” settings cog at the top-right corner.
Click on the Environment in which you want to add your variable(s).
Under the VARIABLE field, enter the name of the environment variable, for example, api_key and add in the INITIAL VALUE field. Enter your Contentstack account-specific value that will replace the variable when making the request.
Once you have defined all the required environment variables, click on Update.
Note: We strongly advise against storing your API keys and tokens in your collection permanently. If you or someone else shares the collection by mistake, other users will be able to export it along with these keys. We recommend that you provide your Contentstack account-specific API keys and tokens in your environment or directly to the sample requests.
Adding Authentication Details in Environment
For users who use authtoken to authenticate their requests, when you make the Log in to your account API Request, your authtoken will be saved in cookies and automatically added to your collection variable.
If you want to discontinue this behavior, you need to whitelist this domain, and then you will be able to access cookies of this domain in scripts programmatically.
Note: To avoid this, we recommend using the stack’s Management Token along with the stack API key to make valid Content Management API requests. For more information, refer to Authentication.
Updating Your Environment
With every new API request added, you need to update your environment file. To get the latest environment variables, download the collection along with the updated environment file again, compare your existing environment with the latest environment, and add the new variables to your existing environment. Once you set up your environment, you are ready to make your API requests.
Step 3 – Make an API Request in Postman
With the Contentstack Postman collection and the environment loaded into Postman, you can now make API requests to the Contentstack API via Postman.
To make an API request, perform the following steps:
Select the environment with which you want to work.
Select an API Request from the Contentstack Postman collection.
Note: If you want to make changes to your variable, you can do it here.
Next, click on Send at the top right to make the API request.
The API request should return with a response under the Body tab in the bottom half of the screen.
Need some more help getting started? Check out the documentations of CDA Postman Collection, CMA Postman Collection, and GraphQL Postman Collection for step-by-step instructions and helpful screenshots.
Step 4 – Update Your Postman Collection
To keep your Postman collection up-to-date, download the latest version of the Postman collection along with the updated environment again, and you are good to go.
Watch the GitHub Channel for Updates
You can also choose to watch for the latest Postman collection updates on our GitHub repository and get notifications of new releases or updates to the repository. To do so, click on the Watch button at the top-right corner of the page and select Watching.
The GitHub Readme doc will help you with the steps that you need to follow.
More Information
For more information on the Postman collections, you can refer the following articles:
Contentstack Documentation
Content Management API
Content Delivery API
GraphQL Content Delivery API
CMA Postman Collection
CDA Postman Collection
GraphQL Postman Collection
GitHub Repository for Contentstack Postman Collection
Update: This blog post has been updated on July 29th, 2020 to accommodate the changes related to the release of our GraphQL API Postman collection.
.png?format=pjpg&auto=webp)
