What is an API?

An API (Application programming interface) is like a secret handshake between computers. It's a way for one computer to talk to another computer and tell it what to do. Think of it like a waiter at a restaurant. You (the client) come in and tell the waiter (the API) what you want (the request) and the waiter goes to the kitchen (the server) and tells the chef (the backend) what to make. The chef makes your dish (the response) and the waiter (the API) brings it back to you (the client). And just like a good waiter, the API makes sure that your order is cooked to perfection and served up just the way you like it!

An API acts as a bridge between the client (such as a mobile app or website) and the server (which houses the databases and logic for the service or application). The client makes a request to the API, specifying the desired action (such as retrieving data or updating a resource) and any necessary parameters. The API then processes the request and returns a response to the client, which can include data, status codes, and other information.

APIs use a set of standard protocols, such as HTTP, to define the structure and format of requests and responses, making it possible for different systems to communicate with each other in a consistent and reliable way.

➡️ Visit Free API to explore some free APIs and experiment with them.

😍 Check out the Open Emoji API too to add your favourite emojis to your apps.

API endpoint

An API endpoint is a specific location within an API that can be accessed by making an HTTP request. The client calls the endpoint to access the functionality of the API. The endpoint typically includes a path or route that defines the resource being accessed and can include additional parameters.

Let's take an example of the Dog API 🐶. Use your browser to visit this link: https://dog.ceo/api/breeds/list/all

Here https://dog.ceo/api/breeds/list/all is an endpoint for a list of all breeds resource within the API. A client could make a GET request to this endpoint to retrieve a list of all dog breeds in the system.

You can go through the documentation of the Dog API to experiment with a few more endpoints.

An API may have multiple endpoints for different resources or functionality.

API Methods

API methods (also known as HTTP methods) are used to perform various actions on an API endpoint.

GET	Retrieves data from the server
POST	Sends data to the server to create a new resource.
PUT	Sends data to the server to update an existing resource.
DELETE	Deletes a resource from the server.
PATCH	Sends data to the server to update specific fields of an existing resource.
HEAD	Retrieves the headers of a resource without returning the body of the resource.
OPTIONS	Retrieves the allowed methods for a resource.

You can download Postman and test these methods for APIs. Here is an example of using the GET method in Postman with Dog API using this URL: https://dog.ceo/api/breeds/list/all

Here is a list of methods that we can check using Postman.

Headers

The HTTP headers are used to provide additional information or context about the request or response.

HTTP request headers are a collection of key-value pairs that are included in the header of an HTTP request.

HTTP response headers are a collection of key-value pairs that are included in the header of an HTTP response.

Here is an example of the headers we get on Postman with Dog API using this link: https://dog.ceo/api/breeds/list/all

Body

The API request body is the data that is included in the body of an HTTP request when making a call to an API. The body of the request is used to send data to the server, such as to create a new resource or to update an existing one.

The API response body is the data that is included in the body of an HTTP response when an API is called. The body of the response contains the data requested or the result of an operation. Use your browser to visit this link: https://dog.ceo/api/breeds/list/all. Whatever it returns is the API response body.

We can even check it out using Postman:

Note: The format of the request and response body will depend on the API

Parameters

API parameters are values that are passed in an HTTP request to an API in order to provide additional information or context about the request.

Header parameters

HTTP request headers are a collection of key-value pairs that are included in the header of an HTTP request.

HTTP response headers are a collection of key-value pairs that are included in the header of an HTTP response.

In these key-value pairs, the values that are passed to the keys are called parameters.

An API request header parameter is a value that is passed in the header of an HTTP request to an API. These parameters are used to provide additional information about the resource to be fetched, or information about the client requesting the resource.

An API response header parameter is a value that is passed in the header of an HTTP response to an API. These parameters are used to provide additional information or context about the response, like its location or information about the server providing it.

Here is an example using Postman:

API keys are typically passed as a request header parameter, rather than in the request body. This allows the server to easily read the key and determine whether the client has permission to access the requested resource. However, some APIs may accept the key in the request body as well. It depends on how the API is designed and implemented.

Query parameters

These are the most common parameter type. It appears at the end of the URL after the question mark (?). The question mark, the parameter, and its real value make what is referred to as the query string.

Nationalize.io predicts the nationality of a person based on their name. Let's consider a sample URL: https://api.nationalize.io/?name=arunima

Here name=arunima is the query parameter. Here is what I get. 😁

{
    "country": [
        {
            "country_id": "IN",
            "probability": 0.454
        },
        {
            "country_id": "BD",
            "probability": 0.086
        },
        {
            "country_id": "NP",
            "probability": 0.079
        },
        {
            "country_id": "AE",
            "probability": 0.077
        },
        {
            "country_id": "SQ",
            "probability": 0.068
        }
    ],
    "name": "arunima"
}

You can try it out with your name too! 😄

Request body parameters

These are included in the body of the request and are used to provide additional information about the resource being created or updated.

The request body should be passed in the correct format specified by the API, otherwise, the request may fail.

An example of a request body parameter in an API could be a JSON object containing information for creating a new user account. The API endpoint for creating a new user account might expect the request to include a JSON object in the request body with the following parameters:

{
    "username": "Arunima",
    "email": "aru123@gmail.com",
    "password": "abc123"
}

Template/Path parameters

An API path parameter is a value that is included in the URL path of an HTTP request to an API. These parameters can be used to identify a specific resource or resources within the API.

Let's use Zippopotam API to get information about a specified ZIP code. Here is an example of an API path parameter: https://api.zippopotam.us/us/33162

Here is what we get:

{
    "post code": "33162",
    "country": "United States",
    "country abbreviation": "US",
    "places": [
        {
            "place name": "Miami",
            "longitude": "-80.183",
            "state": "Florida",
            "state abbreviation": "FL",
            "latitude": "25.9286"
        }
    ]
}

Here, the path parameter 33162 tells the API to retrieve information about that particular pincode.

Try Zippopotam to get information about the zip code of your area. 🌎

Matrix parameters

An API matrix parameter is a value that is included in the URL path of an HTTP request to an API and is appended to the end of a path segment, denoted by a semicolon(;) to provide additional information or context about the request.

Here is an example: http://sample.com/user;name=john

It means from the user resource we want to get information on the particular user with name=john

Matrix parameters are not as widely used as other types of parameters, like query or path parameters.

Status code

Annoying, right? ☹️

Let's learn about them.

HTTP status codes are three-digit numbers that are returned by a server to indicate the status of a client's request.

Each status code consists of a three-digit number, with the first digit indicating the general class of the code. The most common classes of status codes are:

1. 1xx (Informational): The request was received, and the process is continuing. These status codes are rarely used and typically not seen by the user.

2. 2xx (Successful): The request was successfully received, understood, and accepted.

3. 3xx (Redirection): The request needs further action to be completed, such as redirecting the user to another page.

4. 4xx (Client Error): The request contains bad syntax or cannot be fulfilled by the server.

5. 5xx (Server Error): The server failed to fulfil a valid request.

Web developers and system administrators use these codes to understand and troubleshoot issues with their web applications and servers. 🛠

In Postman, you can see the status codes here:

🤖 There are several ways to test HTTP status codes:

1. Use a tool such as Postman to make HTTP requests and check the returned status code. These tools allow you to set the request method, headers, and body and will display the response status code and other information.

2. Use a command-line tool such as curl to make HTTP requests and check the returned status code. For example, you can use the command curl -I http://example.com to check the status code of a website.

3. Write a script or program that makes HTTP requests and checks the status code. This can be done in any programming language that has an HTTP library, such as Python, Java, or JavaScript.

4. Use an online status code checker website like httpstat.us, where you can check the HTTP status code by providing the URL, it will give you the HTTP status code, header and body in a single request.

5. If you have access to the server, you can configure it to return a specific status code for certain URL patterns or conditions, and then test those URLs to see if the correct status code is returned.

Refer to MDN Docs to learn more about them.