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”.
What makes up a Request?
A request is made up of 4 aspects;
- The endpoint (URL)
- The method
- The headers
- 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;
However, the “root-endpoint” for the same URL is;
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.
So from the example above, the path is;
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
In this example the colons (:) denote a variable so simply replace :username with your GitHub username and enter it into the browser address bar.
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 ;
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.
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;
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
$ 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.
$ curl https://api.github.com will return a list of the resources available from the GitHub API;
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;
This is because certain methods are either restricted to protect the integrity of the database or require authorization to proceed.
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.
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;
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" \
That’s the whole breakdown on an HTTP request, but one last thing worth mentioning is the use of 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;
- Include the version in your endpoint.
- 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;
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
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.
REST API For Beginners | SoapUI
Imagine if every PhD dissertation resulted in something that changed the world? Sadly, most end up with a copy on the…
What is REST — A Simple Explanation for Beginners, Part 1: Introduction
This is part 1 of 2 articles explaining the basic concepts of REST.
HTTP/1.1: HTTP Message
part of Hypertext Transfer Protocol -- HTTP/1.1 RFC 2616 Fielding, et al. HTTP messages consist of requests from client…
HTTP: The Definitive Guide
Now let's take a quick look at the structure of HTTP request and response messages. We'll study HTTP messages in…
REST API Versioning - REST API Tutorial
To manage this complexity, version your API. Versioning helps you iterate faster when the needed changes are…