Mastering REST Architecture — REST API Details

In our last post, we’ve learned about REST Architecture details, benefits and constraints, and now we’ll learn REST API with its details.

1.) API

Application Programming Interface

An API is an application programming interface. It is a set of rules that allow programs to talk to each other. The developer creates the API on the server and allows the client to talk to it.

2.) REST API

A REST API is an application program interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data.

REST determines how the API looks like. It stands for “Representational State Transfer”. It is a set of rules that developers follow when they create their API. One of these rules states that you should be able to get a piece of data (called a resource) when you link to a specific URL. Each URL is called a request while the data sent back to you is called a response.

* REST is a way for two computer systems to communicate over HTTP in a similar way to web browsers and servers.

* REST API defines a set of functions which developers can perform requests and receive responses via HTTP protocol such as GET and POST.

3.) The Anatomy Of A Request

It’s important to know that a request is made up of four things:

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

3.1.) The Endpoint
The endpoint (or route) is the URL you request for. It follows this structure: root-endpoint/?

The root-endpoint is the starting point of the API you’re requesting from. The root-endpoint of Github’s API is https://api.github.com.

The path determines the resource you’re requesting for. Think of it like an automatic answering machine that asks you to press 1 for a service, press 2 for another service, 3 for yet another service and so on.

You can access paths just like you can link to parts of a website. For example, to get a list of all posts tagged under “Rest API” on Medium, you navigate to https://medium.com/tag/rest-api.

3.2.) The Method
The method is the type of request you send to the server. You can choose from these five types below:

• GET
• POST
• PUT
• PATCH
• DELETE

These methods provide meaning for the request you’re making. They are used to perform four possible actions: Create, Read, Update and Delete (CRUD).

HTTP Methods

3.3.) The Headers
Headers are used to provide information to both the client and server. It can be used for many purposes, such as authentication and providing information about the body content. Here is a list of valid headers HTTP Headers Reference.

HTTP Headers are property-value pairs that are separated by a colon. The example below shows a header that tells the server to expect JSON content.
"Content-Type: application/json". Missing the opening ".

3.4.) The Data (Or “Body”)
The data (sometimes called “body” or “message”) contains information you want to be sent to the server. This option is only used with POST, PUT, PATCH or DELETE requests.

Sending data as JSON

4.) HTTP Status Codes And Error Messages

HTTP status codes let you tell the status of the response quickly. The range from 100+ to 500+. In general, the numbers follow the following rules:

1. 200+ means the request has succeeded.
2. 300+ means the request is redirected to another URL
3. 400+ means an error that originates from the client has occurred
4. 500+ means an error that originates from the server has occurred

Here is the information about specific HTTP status codes HTTP Status Reference.

5.) API Versions

Developers update their APIs from time to time. Sometimes, the API can change so much that the developer decides to upgrade their API to another version. If this happens, and your application breaks, it’s usually because you’ve written code for an older API, but your request points to the newer API.

You can request for a specific API version in two ways. Which way you choose depends on how the API is written.

These two ways are:

1. Directly in the endpoint
2. In a request header

Twitter, for example, uses the first method. At the time of writing, Twitter’s API is at version 1.1, which is evident through its endpoint:
https://api.twitter.com/1.1/account/settings.json

Github, on the other hand, uses the second method. At the time of writing, Github’s API is at version 3, and you can specify the version with an Accept header:
curl https://api.github.com -H Accept:application/vnd.github.v3+json

Conclusion

• An API is an application programming interface. It is a set of rules that allow programs to talk to each other.
• REST determines how the API looks like. It stands for “Representational State Transfer”. It is a set of rules that developers follow when they create their API. REST uses URL to transfer the data. Each URL is called a request while the data sent back to you is called a response.
• A request consists of 4 parts which are: The endpoint, the method, the headers, the data (or body).
• HTTP status codes let you tell the status of the response quickly.
• Developers update their APIs from time to time. You can request for a specific API version in two ways: directly in the endpoint, and in a request header.

Since we’ve completed the theoretical parts, next post’ll be about a practical implementation: Developing a REST API with Spring Boot Framework. Thus, we’ll find a chance to implement the things about we’ve learned so far!