REST API

What is the REST API?

The REST API is an architectural style for APIs. This means that REST is not a protocol or a standard, it’s just a style for writing APIs. What this means is that an API does not have to be created in the REST style. In order to meet this style, certain things must happen. So describing an API as RESTful, means that an API must have/be:

1. Uniform interface
2. Client-server separation
3. Stateless
4. Layered System
5. Cacheable
6. Code-on-demand

This article will not be going in depth to these things to allow focus on different aspects of the REST API.

REST allows clients to get data(resources) from a specific URL. It relies on client-server relations via the HTTP protocol. HTTP is very important in REST, but is too much to cover. All that is needed to know about HTTP is that it’s how a web browser client and a resource communicate with each other. The client is the person who uses the API. Using Twitter as an example, the client(you) can use the Twitter API to read and write data from Twitter, create a new tweet, retweet existing tweets, etc. This is all on the client side. The server side, however, provides the resource to the client. Sticking with the Twitter example, the resource would be the name of the profile who created the tweet, the tweet itself, and/or a photo. Those were just a few examples of a resource that the server brings back to the client.

Writing in the style of REST is important because most of the web is written in this style, so when creating a web application, why not just write it in a way that most of everything else is written as?

REST stands for Representational State Transfer.

What does the REST API do?

In a REST API call, the server will TRANSFER to the client a REPRESENTATION of the STATE of the requested resource. The representation of the state can be in JSON, XML, or HTML format. JSON is most popular among APIs. It enables clients to take actions on resources. What this means is that a client can create, read, update/change, and/or delete a resource from a database.

Methods of REST

Get-retrieves data from a resource

Post-creates a new resource

Delete-deletes a resource

Put/patch-updates a resource

All of these methods correspond with one of the things that a client can do to a resource: create, read, update/change, or delete. This can be shorted to CRUD. The post method will Create a resource. The get method will Read a resource. The put method will Update a resource. The delete method will Delete a resource. In order for the delete and put methods to work, an id of the resource is required. The client must specify which resource he wants to update/delete in order for the server to correctly update/delete the correct resource.

How does the REST API work?

If the client needs to provide two things for a call to the API and those two things are:

1. Endpoint
2. Method

An endpoint is the identifier of the resource. This is the URL(Uniform Resource Locator). The endpoint allows the API to know which resource the client wants. The method(operation) that the client want to perform is the next thing that needs to be provided. Does the client want to get, post, put, or delete a resource? The client will need to specify this so the API knows what to do.

There are two more things that an API call can have: headers and data.

Headers are used to provide information to both the client and server. The header can help with authentication. The data contains the information the client want to be sent to the server. The data is only needed with post, put, or delete request methods.

After the REST API call:

After the call, an HTTP status error will happen. An HTTP status error will indicate to the client whether the call was successful or a failure. If it was the latter, then the status error will tell the client what’s wrong based on the number of the error. The number will tell the client why it failed. The 1xx errors will just communicate information. 2xx errors will indicate success. 3xx errors will indicate that more steps are needed. 4xx indicate the error was on the client’s side. And 5xx errors will indicate the error was on the server side.

1xx: Informational

Communicates information

2xx: Success

Success

3xx: Redirection

More steps needed

4xx: Client Error

Client’s fault

5xx: Server Error

Server’s fault

Using REST for authentication:

As mentioned before, REST can help with authentication. If an action can alter a database of information on it, authorization should be needed. Altering a database can done by using the post, put, delete methods. So before a user can perform one of those methods, the web has two main ways of proving that the client is allowed to perform these actions. Those ways are with a username/password or with a secret token. Mostly everyone knows about username/password. A secret token can include something called oAuth. oAuth allows a client to authenticate himself with other networks like Github, Google, Facebook, etc. This is only the surface of what the REST API does.