Application Program Interfaces(APIs) are the unofficial language of the internet, and allow servers to successfully transmit data back and forth.

While APIs are the common tongue of the net, a Representational State Transfer(REST) API would be a specific dialect, or as I personally like to think of it: the love language of servers.

REST APIs use the HTTP object to communicate various requests and responses, and though it's guidelines and pattern may seem strict, it is this structure that makes resource access easy and consistent.

This system is similar to that of reading a document that uses proper grammar, indentation, and punctuation vs. reading one that does not. Even with complex content, documents that follow English Language standards are far easier to decipher than those littered with poor grammar, spelling errors, and improper or missing punctuation.

By setting up this backing structure, the flow of an API request runs smoothly and we are able to utilize it's resources in a number of ways. When a REST API is called, the server will transfer a representation of the state of the requested resource from the API, to the client.

Because REST APIs follow their own style standards the more familiar you are with the prototype pattern, the more success you will have when attempting to retrieve resources.

Let's break down the style and structure of this incredibly useful format with some help from my favorite constantly reincarnated, eternally ageless, world-saving hero:

"Wake up, Link!"

Six Rules of REST

The goal of a REST API is to have a completely modular web server, which can be achieved by following these guidelines:

Client-Server Separation

REST APIs require that the retrieved state be stored on the client and not on the server, which improves the portability of the app by separating the concerns of the client, like the view, and the storage concerns of the server.

Stateless

The server sending the request should also be stateless, meaning the server remembers nothing and knows nothing about previous or other calls made to the API. It's only concern is the data contained within it's request body.

Stateless calls can be made independently and each call must contain everything needed for the API to send a successful response.

Cache

Responses from the server send documentation on whether or not the requested resource is cacheable. If so, the resource will be saved to the client cache and wont have to be requested again to retrieve that same results repeatedly.

Uniform Interface

Uniform Interfacing ensures that every request, no matter the client language(chrome, linux, python, etc)is structured in the same manner.

Layered System

The concept of a layered system builds on the idea of the separation of concerns between the client and the server. Between the client request and the API's response, there should be a layered system of independent components.

This is where middle-ware software like 'Express' is use and allows us to create routes from individual components to the API, further separating an application's business logic from it's application logic.

The number of layers don't matter, and they should have no affect on the API's resource request or response; they just must be present.

Code on Demand

Code on Demand is not an actual requirement and is executable code that is sent from a server to a client in a request.

R & R

Requests and Responses are made easy when working with REST API's and the HTTP Request Object, once we finally decide which API best suits our project, we can open the lines of communication to get what we need for our app.

Methods

In any Legend of Zelda game, different quests require Link to use different tools to be completed; the same is true with the REST pattern. Each request requires a different method to access resources. In order to get what we need, we must make sure we're using the right method and structure when making client requests.

Similarly, each Legend of Zelda game, while different in design, landscape and style, all retain the same overarching structure: sleeping hero awakens to a quest, hero battles monsters, hero saves the princess, hero saves the day.

REST API's may vary in the style of how the request should be sent, but the backing structure is always the same: URL, End Path, Headers, and sometimes a Body.

Root Endpoint

Every request from a client must include a root endpoint as well as it's method type. By using the Command Line Interface(CLI) in any terminal, we can practice interacting with REST API's. The curl command sends GET requests by default

                       curl https://api.github.com

Path

The Path follows the end-point and is composed of a relative adjective determined by the developer. This pattern of REST also makes it easier to find exactly what we're looking for, and colons denote the use of a variable.

                 curl https://api.github.com/users/:username

Headers

Headers are optional and often used for authorization methods, Cross Origin Resource Sharing(CORS) and identifying other important information the API might need to process the request. A common use for headers is identifying the content type of a request, when using the CLI, -H denotes the use of a header or series of headers.

curl -H "Content-Type: application/json" https://api.github.com/users/:username

$#Body

Like Headers, a request body is optional, but beneficial in many cases, such as POST requests which are used to create a new resource on the server and save it to the database. The -X denotes the use of a custom HTTP method and the -d identifies the data that is going to be saved.

curl -X POST -H "Content-Type: application/json" -d '{"thisIs: "theBody"}'https://api.github.com/users/:username

Follow these guidelines and request structure and you wont wind up having to deal with this side quest:

In Conclusion

REST API's are just API's styled with a standard. Because they follow a pattern, data access and retrieval via requests and responses are a convenient and consistent way for developers to build out applications with the backing power of websites like Google and Youtube.

GET some REST and thanks for reading!