Introduction
As a developer, you will likely have to work with API whether it be creating a new API or using an existing API provided by another organization.
This guide will show you how to work with APIs using the Postman application by setting up the application and creating endpoints for an existing API.
What is Postman?
Postman is an API client, it's simply a development tool that can be used to help you debug, test, and call endpoints of APIs. Postman allows you to set up calls for API endpoints which can be saved and called repeatedly, without using Postman it would be more work to set up calls for API endpoints manually using something like cURL for example which is used to call endpoints on the command line.
Using Postman
Postman can either be used via the Postman website or as an application, this guide will use the application version.
Setup
Go to the download page for Postman and click the orange button to download the install file.
Go to the Downloads folder and double-click the Postman setup file to install.
After installation, the application should load up and show the Postman application. At this point you can start using Postman however it's recommended to create an account, to begin the process click the orange Create Account button in the top right of the application window.
Your default web browser should open and automatically go to the account sign-up page.
The benefit of creating an account is that all the endpoints you set up are uploaded to the Postman cloud so it's stored online and can be accessed from multiple machines by logging into your account.
Fill in the email, username, and password and click the Create Free Account button to progress forward or use an existing Google / Single Sign On account.
On the next page fill in your name, select an option for your current role, and then click the Continue button.
On the next page select the account you just created, for the below screenshot the account is Tester.
Tick the checkbox and click the Allow button to switch back to the Postman application.
You will notice an avatar on the top menu, click it and it will show your current account details indicating that you are logged into the account.
Accessing an API
Now that you have Postman set up you can begin trying out Postman to see how it works, there is an API available at https://api.devpushprojects.com which will be used to create some endpoints and run them to see how interacting with the API works.
Creating an environment
An environment is a list of key-value pairs representing data you should use for your endpoints such as an API URL and authentication token.
Select the Environments tab on the left menu and click the plus icon to add a new environment.
Add the following values for the environment variable.
- Variable: base_url
- Type: default
- Initial value: https://api.devpushprojects.com
- Current value: https://api.devpushprojects.com
Name the environment Countries API.
On the right side where it shows No Environment click the drop-down and select Countries API to make the environment active.
Creating a collection
A collection is essentially a folder where you store all your endpoints. Typically it's best to associate a collection with a specific API so it's easy to organize multiple collections in your account.
Select the Collections tab on the left menu and click the plus icon to add a new collection.
A pop-up menu will appear, select the REST API basics as this option will give you a template with default endpoints added.
You will see the collection added which is named REST API basics: CURD, test & variable and a list of four endpoints with the types Get, Post, Put, and Delete which will be explained when setting up the endpoints in the next sections.
Get endpoints
GET endpoints are used to get data from an API, GET endpoints can either return a list of items or a single item with the ID of the item specified.
There will be two GET endpoints to be set up for this collection so right-click the GET endpoint and select the Duplicate option to duplicate the GET endpoint.
Select either of the two GET endpoints and change it, click on the name to rename it to Get countries.
For the URL use the following text.
{{base_url}}/countriesThe {{base_url}} part will refer to the environment variable that was added earlier, this means you only need to change the actual API URL in one place.
Click the Send button to call the endpoint and you should see the data returned back from calling the endpoint.
This is the whole result that should be returned back from the endpoint, the IDs might be different from the list shown below.
{
"data": [
{
"id": 1,
"name": "United States Of America"
},
{
"id": 2,
"name": "China"
},
{
"id": 3,
"name": "Germany"
},
{
"id": 4,
"name": "Japan"
},
{
"id": 5,
"name": "India"
},
{
"id": 6,
"name": "U.K."
},
{
"id": 7,
"name": "France"
},
{
"id": 8,
"name": "Italy"
},
{
"id": 9,
"name": "Brazil"
},
{
"id": 10,
"name": "Canada"
}
]
}For the next endpoint use the {{base_url}}, also in the Params tab fill in the parameter value for the ID with any ID referenced in the above countries list.
{{base_url}}/countries/:idClick the Send button to call the endpoint and return the data matching the sent ID.
Post endpoint
The Post endpoints are used to create data, register accounts, log into accounts, etc.
Use the following URL and name the endpoint Post country.
{{base_url}}/countriesSelect the Body tab, select raw as the drop-down option, and then select JSON. Use the following text below to add a new country Spain and then click the Send button to create the country.
{
name: "Spain"
}After calling the endpoint you should see the text returned showing the entry for the new country which has been added to the country API database.
Put endpoint
Put endpoints are used for editing existing data items, for this API you would use the Put endpoint to change the name of an existing country.
The following shows an existing country named U.K. which will be changed in the Put endpoint to be set up.
Use the ID for the U.K. entry returned in the countries list GET API endpoint called earlier.
Use the following for the URL and use the id that represents the UK.
{{base_url}}/countries/:idUse the following text below for the Body with the same settings as the above Post endpoint.
{
name: "United Kingdom"
}Run the endpoint and the updated country will be returned with the updated country name.
Delete endpoint
The final endpoint to set up is the Delete endpoint, use the following URL and then select a valid country ID from the list of countries after running the Get countries endpoint.
{{base_url}}/countries/:idRunning the endpoint won't return anything as the country will be deleted. You will notice that the status code returned as 204 No Content which means the delete was successful.
You can also re-check the country by using the same ID on the Get country endpoint and seeing if the country exists. You should receive a 404 Not Found response with the error message indicating that the country doesn't exist anymore.
Naming collection
After going through the endpoints the collection name wasn't changed. It can be changed by right-clicking on the name on the right panel and then selecting the Edit option.
Change it to Countries API and press Enter to apply the change.
History of endpoint calls
Another option available on the left-hand menu is the history tab.
This will show a list of all the endpoints that have been run, while going through setting up all the endpoints for the Countries API the history tab will show all the endpoints that were called.
Conclusion
After completing this guide you will have Postman set up so it's ready to write up API endpoints.
After creating some API endpoints and using the https://api.devpushprojects.com API to successfully set up a group of API endpoints in Postman and run each to either get from the API or change data available from the API.
You now have the essential knowledge to use Postman that will assist you during your API development.