A Simple Guide to Understanding Rest API’s

If you googled this article then you are likely looking for some answers to help you with your API issues. Many explanations of APIs rely on complex terminology or technical phrases that obstruct initial understanding. I will keep this article light in order to make it easily understandable for all experience levels.

To start with, you will need to know some specific terminology as it will be repeated throughout, some of which may be new concepts.

API (Application Programming Interface) acts as an intermediary between different programs. You could imagine it like the wire that connects two pieces of hardware. For example, a computer tower and its monitor. APIs follow a set of rules that allow the server and the client1 to “talk to one another”.

REST (REpresentational State Transfer) is an architectural style for the APIs. So it’s an agreed style or pattern for constructing APIs. It determines the URL you would see in the browser and what “response” or data is attached to that URL.

REST has been a primary choice for developers as it works with plain text, XML, HTML, and JSON. Any API architectural style that complies with REST’s architectural constraints and agreements is said to be RESTful. These standardized set of constraints will make the API easier to use and understand, much like how traffic laws or traffic lights are largely the same the world over.

A key concept to help one’s understanding is that the *URL (Uniform Resource Locator) you might type into the browser is a “request” for information from you (the client — the person or software who is using the API) to a distant server holding the information.

This request might simply be used to display an entire website, or it could be for particular data to be returned. This information is called the “response”.

Simple HTTP communication.

What makes up a Request?

A request is made up of 4 aspects;

1. The endpoint (URL)
2. The method
3. The headers
4. The body (or data)

1) The Endpoint

As the URL is an identifier for a set of information (resource), it is also known as an “endpoint”.

The “resource” described by the URL could be an object, an image, or even a simple data type like a string.

For example, an endpoint might look like this one below;

https://pokeapi.co/api/v2/pokemon/charizard

However, the “root-endpoint” for the same URL is;

https://pokeapi.co/api/v2/

The root-endpoint is the starting point of the API you are requesting from.

The “path” is what determines the specific resource you are requesting for. It follows on from the root-endpoint, much like navigating a regular website.

Breakdown of an endpoint.

So from the example above, the path is;

/pokemon/charizard

or;

/{resource}/{name}

The paths that are available to you should be listed in the API documentation.

Another great resource to practice this with is the GitHub API (assuming that you have an account). You can request a complete list of your own repositories using the root-endpoint; https://api.github.com and the path /users/:username/repos

In this example the colons (:) denote a variable so simply replace :username with your GitHub username and enter it into the browser address bar.

Eg; https://api.github.com/users/octocat/repos

Query parameters

The final section of an endpoint is the “query parameters”. Technically query parameters are not part of the REST architecture but you will see many APIs use them. Query parameters allow you to modify a request using key-value pairs. They will always begin with a question mark (?), followed by the Key. The Key and Value are separated by an equal sign (=).

Multiple query parameters can be chained together. In that case, each parameter pair is separated by an ampersand (&).

An example might be; ?query1=value1&query2=value2

For example ;

https://pokeapi.co/api/v2/pokemon?offset=20&limit=20

The above example limits the number of pokemon returned to 20, and the offset deals with pagination. Therefore this represents the second page of the results.

_____________________________

2) Methods

Depending on what you want to do with the resource, there are several HTTP Methods (or actions) that the server will perform on the resource. These are; GET, POST, PUT, DELETE, and PATCH.

These correspond to CRUD operations -Create, Read, Update, Delete.

GET = The default request. It performs a Read operation and returns the data in the response.

POST = Creates a new resource on the server (creating a new entry in the database) and returns whether or not it was successful.

PUT = Updates a resource on the server and returns whether or not it was successful.

DELETE = Deletes a resource from the server and returns whether or not it was successfully deleted.

PATCH = Partially updates an existing resource and returns whether it was successful.

The API documentation should tell you what type of method to use for specific requests. Eg;

Taken from the pokemon API at (https://pokeapi.co/docs/v2#pokemon)

Making requests from the Command Line

In order to make requests from the CLI (Command Line Interface), you will need a command-line utility such as cURL or httpie.

For the sake of demonstration and because most API documentation is written for cURL, I would recommend installing cURL. Follow the instructions and test it is installed with the command $ curl --version

To use cURL, simply type ‘curl’ followed by the endpoint into the command line. For example;

$ curl https://pokeapi.co/api/v2

or

$ curl https://api.github.com

Some servers return unformatted JSON which can be difficult to read. For this reason and simplicity's sake, I will use the GitHub API for future examples.

JSON (JavaScript Object Notation) is a common formatting type for sending and requesting data using REST APIs and looks identical to a Javascript Object.

A simple Javascript object

$ curl https://api.github.com will return a list of the resources available from the GitHub API;

GitHub API resource list.

We can send a request using curl by writing -X or --request before the method and the URL (these are called flags).

$ curl [FLAGS] [METHOD] URL

If we try to use curl to make a POST request and create a repository on GitHub API, we can type;

$ curl -X POST https://api.github.com/user/repos

We should see this response returned;

Error message; “Requires authentication”

This is because certain methods are either restricted to protect the integrity of the database or require authorization to proceed.

Authentication

An API might be entirely read-only, as a means to share information — such as a learning resource. But even read-only files might need security, for example, banking / payment information. As PUT, POST, PATCH, and DELETE methods will alter the database, they nearly always require authentication for this reason.

It is important to understand the difference between authorization and authentication.

Authentication — the verification of the credentials of the connection attempt.

Authorization — is the verification that the connection attempt is allowed. Authorization therefore occurs AFTER a successful authentication.

This means that authentication is saying who you are, and authorization is confirming that you have access to that resource.

There are two main methods of authentication;

• Basic authentication
• Secret token authentication

Basic authentication can be handled using a special HTTP header where we add ‘username:password’. The issue with this method is that these credentials are encoded and not encrypted. Meaning that these passwords are hashed and in theory could be decoded. They are secure but not to a high enough standard. Furthermore, we need to send over the password on every request as they are only valid once.

To perform basic authentication using curl from the command line, we would add the -u option after our POST command, as follows;

$ curl -x POST -u "username:password" https://api.github.com/user/repos

However, this would also leave your username and password in the history of the terminal and compromise security. When working with REST APIs, security must always be considered from the outset.

The current standard is the secret token method as championed by OAuth. Essentially it lets you authenticate yourself by allowing you to log in via a trusted service such as GitHub, Google, or Facebook. However, explaining that is beyond the scope of this article. For more information, there is an excellent 5-minute video posted on their website.

3) Headers

Headers provide information to both the client and the server. Essentially they are meta-data for the request and can be used for a variety of purposes. These include; setting the content type, the connection type, authentication, response cookies, or API version. I will discuss more about API versions later.

You can send HTTP headers with curl by using the -H or --header option.

For example, you might want to set the connection type to keep-alive as a way to reduce the time needed to serve files if multiple requests were needed. This would be written:

$ curl — header “Connection: Keep-Alive” https://api.github.com

(Note: this is for demonstration purposes only. By default, HTTP connections close after each request)

You can also view the headers that you have sent by using the -V or --verbose option:

$ curl — header “Connection: Keep-Alive” https://api.github.com -v

The above command a plethora of information:

Above, * refers to additional information provided by cURL. > refers to request headers, and < refers to the response headers.

4) The body (data)

HTTP body data is the information sent in an HTTP transaction message directly after the headers. It can be the request message data from the client or the response message data from the server. Data in the body is optional and can be any kind of data (eg images, video, audio and / or text).

It could be that a GET request message from the client has no body (because it is not needed to GET a document from the server). The server would then send back an HTTP response message which contains the HTTP version number (HTTP/1.1), a success status code (200) with a descriptive phrase (OK), the block of response header fields, and finally the response body. This could be the HTML of a website for example.

Using the previous query from above we can see;

The version number and status code of the response

If you wanted to send data in the initial request (i.e something other than a GET request), you can send data using cURL by using the -d or - -data option:

$ curl -X POST <URL> -d property1=value1

To send more than one key-value pair, you must use another -d option:

$ curl -X POST <URL> -d property1=value1 -d property2=value2

It is worth noting that by default, cURL sends data as if it were delivered via “form fields” on a web page. If you want to send JSON data, you will need to set the Content-Type to application/json by sending a header, and you will also need to format your data like a JSON object in the command line.

curl -X POST <URL> \
  -H "Content-Type: application/json" \
  -d '{
  "property1":"value1",
  "property2":"value2"
}'

That’s the whole breakdown on an HTTP request, but one last thing worth mentioning is the use of API versions.

API Versions

Rest doesn't provide any specific versioning guidelines, so approaches to it can vary. If your app is reliant on an API, it is possible that the developer will upgrade their API to a newer version which can cause issues or even break your program entirely. This is because your code is based on their old software but the requests use the new API version.

If an API update has caused breaking changes, you can request a particular API version by either;

1. Include the version in your endpoint.
2. Using a request header.

Including the version in the endpoint is the most common and straightforward approach — although by including it in the URL developers are guaranteed to break the client integration when the version changes. The Twiter API for example uses this first approach;

https://api.twitter.com/8/accounts

The second approach requires the API client to provide the version using the Accept (request) header. It is the preferred way to version APIs as it keeps the URLs clean. As part of the response, you can check the version in the response’s headers. For example, this request to GitHub contains no API version in the URL:

$ curl https://api.github.com -H Accept:application/vnd.github.v3+json -v

The version is included in GitHub’s response

In Summary

In this article, we learned that APIs are software built in a standardized way to control how two applications talk to one another. We covered the definition of a REST API, the components of an HTTP request and response, how we can read, edit, update and delete information using these requests. Security and versions were also briefly touched upon. For further information, please use the resources below to further your understanding.
I hope this article has helped, and please feel free to comment below with any suggestions or corrections, or even just to say hi.

And a special thanks to PokeAPI for being awesome.

________________

Sources:

https://pokeapi.co/

https://api-university.com/blog/styles-for-apis-soap-rest-and-rpc/#:~:text=In%20this%20blog%2C%20we%20study,and%20disadvantages%2C%20commonalities%20and%20differences.

https://pusher.com/tutorials/understanding-rest-api

REST API For Beginners | SoapUI

https://www.mulesoft.com/resources/api/what-is-an-api#:~:text=API%20is%20the%20acronym%20for,you're%20using%20an%20API.

https://blog.restcase.com/restful-api-authentication-basics/

What is REST — A Simple Explanation for Beginners, Part 1: Introduction

https://www.smashingmagazine.com/2018/01/understanding-using-rest-api/

HTTP/1.1: HTTP Message

HTTP: The Definitive Guide

REST API Versioning - REST API Tutorial

https://hmh.engineering/rest-api-versioning-strategy-at-hmh-f0e01d3b0190

https://docs.github.com/en/rest/overview/media-types#request-specific-version