Note: This article is meant for those with little to no knowledge on how to call an API.

• 1.Purpose
• 2. Overview
  • 2.1. What is an API? Why using API?
  • 2.2 Types of API
• 3. Demo: How to call API with Postman
  • 3.1. Structure of an API documentation
  • 3.2. Get data from Pokemon table
    • 3.2.1. The tool to make API request
    • 3.2.2. Detect the required input to make API request
    • 3.2.3 Getting the inputs into Postman
    • 3.2.4. Advanced – Path Parameter
    • 3.2.5. Advanced – Query Parameter
• 4. Terminologies

1. Purpose

After you read and practice alongside this article, you will know how to perform an API call with GET method using Postman, and understand the related terms.

2. Overview

2.1. What is an API? Why using API?

In a nutshell, the API of a software (let’s name this software A) is a tool, which allows another software X to interact with software A.

Example: Facebook provides a Facebook API. Using this API, you can write a software / code script to interact with your Facebook account, instead of the slow point-and-click interaction.

This interaction provided by API is divided into 2 main categories:

• Get the current data on software A. Example: Using Facebook API, you can see the information about your account, like what is the account name, how many friends / posts the account has.
• Edit / Create new data on software A. Example: Using Facebook API, you can edit the posts on your profile, or create a new post.

So why using API? Because of automation. Translating actions into code script allows for automation, resulting in much faster execution speed than regular interaction (point-and-click for example).

2.2 Types of API

API is often categorized by format into 4 main categories: RPC, SOAP, REST and GraphQL. REST is one of the most popular API format these days. So this article will demo using a public REST API.

3. Demo: How to call API with Postman

This article will use Poke API, a public REST API for demonstration. Poke API is provided to interact with the public Pokemon database. I use the Pokemon resource (what is a resource? see explanation later on). Poke API documentation is here: https://pokeapi.co/docs/v2

3.1. Structure of an API documentation

The API documentation usually categorizes itself into parts. Each part is a data table you can get using API.

For example, looking at Poke API documentation, you can see there are table groups called Berries, Contests, Encounters, Evolution, …

Within each table group, there are a list of tables you can get using Poke API. These tables are called API resources. For example, within the Pokemon group, there is a Pokemon table, which list out all Pokemons.

So using an API documentation, we will know which tables/resources we can get using this API.

3.2. Get data from Pokemon table

3.2.1. The tool to make API request

To use API, we need a tool to make API requests. The most popular tools are:

• Postman: a web-app / desktop-app mostly used for testing API requests
• CURL: a command-line tool
• A programming language (i.e. Python)

I’ll use Postman for this demo. You can use the web version of Postman at http://postman.com. Sign in with your Google account, create profile if this is the first time you use Postman, and you’re ready to go. After signing in, you will arrive at the screen in the video below. Click on Create New > HTTP Request to start making API request.

3.2.2. Detect the required input to make API request

What you need:

To make an API request, you need 3 inputs at the very least:

• Endpoint: The URL to the data table
• Method: The interaction method to be used with the endpoint
• Authorization: The method of authorization against the API system.

Demo:

When you look at the Pokemon table, you will see the following info on Endpoint and Method:

In the picture, you can see the Method is GET. The Endpoint is https://pokeapi.co/api/v2/pokemon

The latter part, {id or name}, is called a path parameter. The path parameter can either be mandatory or optional. For Poke API, it is optional. How do you know that? It is mentioned in the Resource Lists/Pagination section. (Calling any API endpoint without a resource ID or name will …)

The last input we need is Authorization. Public API like this means that anyone can use it without authorization. So the Authorization method is No Auth.

To sum up, here are the inputs we will use to get data from Pokemon table:

• Endpoint: https://pokeapi.co/api/v2/pokemon
• Method: GET
• Authorization: No Auth

3.2.3 Getting the inputs into Postman

Demo:

On the new Untitled Request of Postman, enter the endpoint and choose GET method

Switch to the Authorization tab and make sure you choose No Auth (see more types of Authorization in the Terminologies section)

Click the Send button to send the API request. When the Status Code return 200 OK, it means you have made a correct API request, and data is returned. See the Terminologies section on Status Code to know more about popular Status Codes.

3.2.4. Advanced – Path Parameter

Path parameter definition was mentioned in section 3.2.2 . Path parameter is commonly used to get details on one single object.

For example, you want to get details about a specific Pokemon, like Pikachu. You can use “pikachu” as a path parameter and insert into the endpoint.

Demo:

To see the specific details about Pikachu, the inputs for our API requests are:

• Endpoint: https://pokeapi.co/api/v2/pokemon/pikachu
• Method: GET
• Authorization: No Auth

Let’s edit the endpoint in Postman and hit Send

The returned data is the details about Pikachu. So using the path parameter, you have retrieved data about Pikachu.

3.2.5. Advanced – Query Parameter

API can supply a method to filter, order and limit the returned data. That method is usually through a Query Parameter. Some docs refers to Query Parameter as only Parameter. As a result, it is easy to mistake between Query Parameter and Path Parameter.

Demo:

For Poke API, there are only a few Query Parameters. One of those allow API requests to limit the number of returned records. It is described in Resource Lists/Pagination section.

According to the description, you can add a Query Parameter named “limit” and the number of records we want, and the API will only return the specified number of records. For example, you want to get the first 2 pokemons on the Pokemon table. Then the input for our API request will be:

• Endpoint: https://pokeapi.co/api/v2/pokemon
• Method: GET
• Authorization: No Auth
• Query Parameter:
  • limit : 2

Enter the Query Parameter at the Params tab in Postman. Postman will automatically input these parameters into the Endpoint. Click Send.

The returned data only show 2 pokemons instead of 20 if you don’t use a Query Parameter. You have successfully limited the returned data.

 

Where to go from here?

If you have followed the instructions above, then congratulations, you have known how to make an API request with GET method. Next up, you can try practice with:

• POST method
• Other types of Authorization listed in Terminologies section.

4. Terminologies

• Host: The server address to call API. It could have the form of an IP address, or a web domain name. Example 1: https://pokeapi.co/api/v2 ; Example 2: https://192.168.11.1
• Resource: The part after Host in the API Endpoint to point to the data table. For example: pokemon
• Path Parameter: The part after Resource in the API Endpoint to point to a specific object in the data table. For example: pikachu
• Endpoint: The full address to send the API request to. Endpoint = Host + Resource + Path Parameter. For example: https://pokeapi.co/api/v2/pokemon/pikachu
• Method: The way to interact using the API. 2 most common methods are GET and POST.
  • GET is mainly used to extract data on a software
  • POST is mainly used to edit / create new data on a software
• Authorization: Some API may requires login / access token to make API requests. This is called Authorization. Some forms of Authorization are:
  • No Auth: No Authorization needed. Applied to public APIs like Poke API
  • Bearer: You are provided with a string of characters called an access_token to use the API. Provide this access_token in the API request before sending.
  • Basic: You are provided with a username and a password. Provide these info in the API request before sending.
  • OAuth2: The most complicated and secured Authorization method on the market now. Ask for help if you see this method.
• Query Parameter: Provide a way to filter/order/limit data. Input the Query Parameter in a key-value form.
• Status Code: A 3-digit number to indicate request result. The most common Status Codes are:
  • 200: OK – Successful API request
  • 401: Unauthorized – There’s something wrong with the provided info in Authorization > Check your Authorization again
  • 404: Not Found – Cannot find the specified data table (resource) > Check your Endpoint again