API 101: Make API Calls - Introduction to Restful APIs (4)

This module will take you through HTTP methods for actions performed by API, common API responses and authorization headers.

Before we delve deeper into contextualizing the API with actions, let's visit some concepts that we may have mentioned earlier.

When you make requests with the endpoints, you get responses that contain information, often in JSON format. This is the core of how REST APIs work — you send a request and get a response.

Now let's get into these concepts.

REST (Representational State Transfer) is a software architectural style with a set of web API architecture principles.

There are many types of APIs but RESTful APIs are the most used nowadays. REST APIs, also known as RESTful APIs, enable you to develop any kind of web application having all possible CRUD (Create, Retrieve, Update, Delete) operations.

RESTful systems support storing and exchanging data in different data formats, such as plain text, HTML, YAML, XML, and JSON. This is one of the reasons REST is a prevailing choice for building public APIs these days. Before REST, a popular way to share data was the Simple Object Access Protocol (SOAP) which uses the XML format to exchange data.

In the first module, we explained how an API works and how to send a request when an API call is made. The first thing we need is the Uniform Resource Identifier (URI) of the server or external program.

Take for example the Spotify Web API.

The Spotify Web API is based on REST principles. The query address of Web API is https://api.spotify.com, which is the address where all the request goes. The API provides a set of endpoints, each with its own unique path.

Based on simple REST principles, the Spotify Web API endpoints return JSON metadata about music artists, albums, tracks, and podcasts, manage your Spotify library, and control audio playback, all directly from the Spotify Data Catalogue.

RESTful architecture complies with six architectural constraints for building applications that work over HTTP:

uniform interface
stateless
caching
client-server architecture
layered system of the application
the ability for servers to provide executable code to the client

What Programming Languages Can We Use?

It doesn't matter what programming language you're using, every modern language supports RESTful APIs.

However, remember from our earlier module on How does an API work?, APIs use JSON format instead of using HTML format, unlike web browsers.

The modern API adheres to REST principles and the JSON format and is typically built for HTTP. This results in developer-friendly interfaces that are easily accessible and widely understood by applications written in Java, Ruby, Python, C, PHP, JavaScript and many other languages. Browsers use JavaScript for their API requests, while servers use any language that runs on the computer.

HTTP Request Methods, How do they work?

Let's do a quick recap to understand how HTTP works. The client sends an HTTP request and the client answers with an HTTP response.

An HTTP request has varying parts

Method, or verb
Address, or URL where the data is requested
Header
Body

For this section, we're focusing on the HTTP method.

Web APIs that comply with REST architectural constraints, and RESTful APIs, use HTTP methods to work with resources.

The HTTP Method tells whether requested data in the request-URI is to be retrieved from the endpoint or to be created/updated to the resource.

REST guidelines suggest using a specific HTTP method on a particular type of call made to the server.

The methods commonly used in APIs are:

Let's say you want to make an order online, with a POST request you will create an order, with a GET request you can review the order to confirm that everything is good, with a PUT request you can update the order to make changes, with the DELETE request you can delete the entire order.

In HTTP specification, The methods GET, HEAD, PUT and DELETE are Idempotent methods, they produce the same results if executed once or multiple times. This means that an operation can be repeated or retried as often as necessary without causing unintended effects.

The best way to fully understand REST APIs is to get hands-on practice.

With Bannerbear.com, you can turn your graphic templates into an API to auto-generate social media visuals, e-commerce banners, podcast videos and more. Automating this process gives you more time to focus on the overall marketing strategy without taking up headspace.

To integrate data, you need to have access to the API. Bannerbear provides access to its API Reference.

Send a GET request

This is a common request type where the server is prompted to get data.

A GET request is simple to initiate. When you load a website, that’s a GET request to retrieve a resource/information from another computer. This request does not relate to performing a task, modifying, changing the resource, creating, updating or deleting data. Thus, they are said to be safe/idempotent methods.

As stated earlier, GET APIs are idempotent, making multiple identical requests produce the same result every time until another API (POST or PUT) changes the state of the resource on the server.

Here's a sample GET request to retrieve a video on Bannerbear.

Send a POST request

POST methods are used to create a new resource in the collection of resources. The request will ask another computer to create a new resource and then returns data about the newly created resource.

With POST requests, a URL is used as the endpoint. You don’t include an id in the URl when using the POST method. POST requests are made on resource collections.

Unlike GET, HEAD, PUT and DELETE, POST is neither safe nor idempotent. With non-idempotent operations, the algorithm may have to keep track of whether the operation was already performed or not. Thus, invoking two identical POST requests will result in two different resources containing similar information.

Now let's use Postman to make a POST request using httpbin.org, a simple HTTP Request & Response Service. Base URL: httpbin.org/

Open a new tab on Postman and select the POST HTTP method. Enter the request URL httpbin.org/post.

To send some POST data with the request using JSON format, navigate to the body tab > Raw > JSON to input the example we used earlier.

Here are the details we're working with:

Add this to the request body as raw JSON:

You should get this response:

A POST can be made when a file is subordinate to a directory containing it, or a row is subordinate to a database table.

Send a PUT request

Like POST and DELETE requests, a URL is used as the endpoint. Unlike PATCH requests, this request will ask the server to edit/update an entire existing resource. If the resource doesn't exist and cannot be updated, the API might decide the CREATE (CRUD) a new resource.

When a new resource is created by PUT API because it cannot be updated, the origin server MUST inform the user agent via the HTTP response code 201 (Created) response and if an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.

Unlike POST requests which are made on resource collections, PUT requests are made on a single resource.

Send a DELETE request

Like POST requests, a URL is used as the endpoint. The request will ask another computer to delete a single resource or list of resources identified by the Request-URI.

If you DELETE a resource, it’s removed from the collection of resources. Repeatedly calling DELETE API on that resource will not change the outcome. However, calling DELETE on a resource a second time will return a 404 (NOT FOUND) since it was already removed.

PATCH Requests

A URL is used as the endpoint. The request will ask another computer to make an update on a piece of a resource. Not all browsers or frameworks support PATCH requests.

Unlike PUT requests which also modify a resource entity, the PATCH method partially updates an existing resource, while PUT replaces a resource in its entirety.

Common API Responses, What are they?

When a request is made from a server using GET, POST, DELETE, PATCH, or PUT, it attempts to fulfil the request and the server returns the data (Response) to the client.

The response headers and body follow the same format as requests, accompanied by HTTP Status Codes to tell what is right or wrong. The status code lets you know if the request was processed successfully or unsuccessfully.

Status codes are three-digit numbers issued by a server to communicate the results of a client's request made to the server.

Now let's understand the status code behind HTTP responses.

Common HTTP Status Codes include:

2 —- Success Codes

3 —- Redirection Codes

4 —- Client Error Codes

5 —- Server Error Codes

httpstatuses.com is an easy-to-reference database of HTTP Status Codes.

Send a request with Spotify API

Let's attempt to send a request to get Spotify catalog information about a show’s episodes.

You'd need to update the Spotify ID for the show and string.

Response example

Now let's use Postman to see what happens when there is an error. The status code will explain the issue so you can correct it and try again.

For example, when trying to fetch information without authentication:

The 401 (unauthorized) HTTP response code indicates that the user revoked a token or the access token has expired. This is evident because all requests to Web API require authentication.

You need to generate a valid OAuth Access Token and use the same token in your API call as an Authorization Bearer token. Once the authorization is granted, the authorization server issues an access token, which is used to make API calls on behalf of the user or application.

Now let's repeat this with a Spotify episode from My First Million podcast with Spotify ID 1yZSb2g1XTg5JpQpipnWPQ.

We'll use cURL to retrieve information about a playlist using the Get an Episode endpoint:

To process an API request, Spotify expects the API key to be included in a header to allow access to the tracks.

If everything goes correctly, you will receive a 202 - OK response similar to this:

The response format is in JSON, which is a reflection of all the data sent from the request.

You can try this with Official playlists on Spotify:

New Singles: http://open.spotify.com/user/spotify/playlist/5JOn3LSfpbCrOQ7azB4S6C

New Albums: http://open.spotify.com/user/spotify/playlist/3Yrvm5lBgnhzTYTXx2l55x

Use cURL to retrieve information about a playlist using the Get a playlist endpoint.

Bannerbear uses the following status/error codes:

Authorization Headers

Using the previous example from How to send a POST request, we'll go over the HTTP header used to hold credentials.

The header tells the API about your request and the response you’re expecting. It shows some additional information, for example, the content-type, user-agent, content-encoding, and date. The API will understand what you’re asking and responds in a way that’s easy for you to understand and use.

Postman automatically adds headers in order to communicate with the server.

Headers can be used to add some authorization and authentication data, like the data required by the Spotify request. If you are using a partner or private API and need to authenticate to allow the server to have access, this information can be added to the header.

Now that you understand how to test an API call, you can start evaluating different APIs and narrow down which suit your app and users best. The next module will cover using weather APIs and common scenarios.

📎 PREVIOUS MODULE - Understanding the Mechanics of API Interactions

📎 NEXT MODULE - Using Weather API in Postman

ABOUT ME

I'm Juliet Edjere, a no-code expert focused on design, product development, and building scalable solutions with minimal coding knowledge.

I document all things product stories, MVP validation, and how designs, data, and market trends connect.

Visit my website → built with Carrd and designed in Figma