API - Application Program Interface

An API is a set of definitions and protocols for building and integrating application software It’s sometimes referred to as a contract between an information provider and an information user, establishing the content required from the consumer (the call) and the content required by the producer (the response). For example, the API design for a weather service could specify that the user supply a zip code and that the producer reply with a 2-part answer, the first being the high temperature, and the second being the low

In other words, if you want to interact with a computer or system to retrieve information or perform a function, an API helps you communicate what you want to that system so it can understand and fulfill the request.

You can think of an API as a mediation between the users or clients and the resources or web services they want to get. It’s also a way for an organization to share resource and information while maintaining security, control, and authentication

Another advantage of an API is that you don’t have to know the specifics of caching, how your resource is retrieved or where it comes from

APIs are important in a lot of contexts, such as OS, IoT and of course, the Web. Since I don’t have enough knowledge yet, we’re going to talk over only about Web today. Before continuing, make sure you are comfortable about HTTP.

REST API

REST stands for Representational State Transfer and was created by computer scientist Roy Fielding.

A REST API (also known as RESTful API) is an application programming interface (API or web API) that conforms to the constraints of the REST architectural style and allows for interaction with RESTful web services. It’s NOT a protocol or a standard.

When a client request is made via a RESTful API, it transfers a representation of the state of the resource to the requester or endpoint. This information, or representation, is delivered in one of several formats via HTTP: JSON (JavaScript Object Notation), HTML, XLT, Python, PHP, or plain text. JSON is the most generally popular file format to use because, despite its name, it’s language-agnostic, as well as readable by both humans and machines.

Since REST is not a protocol, there isn’t an official standard for RESTful APIs, so in order for an API to be considered RESTful, it has to conform to these criterias

• A client-server architecture made up of clients, server and resources, with requests managed through HTTP.
• Stateless client-server communication, meaning no client information is stored between get requests and reach request is separate and unconnected.
• Cacheable data that streamlines client-server interactions.
• Uniform interface between components so that information is transferred in a standard form. This requires that:
  • resources requested are identifiable and separate from the representations sent to the client.
  • resources can be manipulated by the client via the representation they receive because the representation contains enough information to do so.
  • self-descriptive messages returned to the client have enough information to describe how the client should process it.
  • hipertext/hypermedia¹ is available, meaning that after accessing a resource the client should be able to use hyperlinks to find all other currently available actions they can take. (Hateos)
• A layered system that organizes each type of server (those responsible for security, load-balancing, etc.) involved the retrieval of requested information into hierarchies, invisible to the client.
• Code-on-demand(optional): the ability to send executable code from the server to the client when request, extending client functionality.

[!info] The REST interface is designed to be efficient for large-grain hypermedia data transfer, optimizing for the common case of the Web, but resulting in an interface that is not optimal for other forms of architectural interaction.

The misunderstanding of REST

Imagine you need to develop a very simple API to retrieve some data. It could be pretty straight forward to develop if you don’t think much about REST. Following only HTTP specs you are able to develop a reasonable API that might fullfil your expectations.

REST doesn’t add any specific functionality to HTTP and just as said above, REST is not a well defined standard or protocol while the HTTP is.

Think of REST a way of extending HTTP functions but keep in mind that you must follow the constraints to achieve this.

Some might argue about the REST standards, of course it has use cases, but implementing them for everything is another story. Always remember that the developer’s job to choose the right tools for the work, otherwise the promised remedy can be worse than the decease.

sources

• Redhat - What is an API
• Roy Fielding - REST Arch
• REST is the new SOAP and the follow-up article