HTTP APIs

We will see two types of protocols over HTTP: one stateless and another stateful.

RESTful API

REST (Representational State Transfer) is an architectural style for distributed systems. Allows applications to communicate with services provided on the web. In order for an interface to be called RESTful, it must meet a number of principles:

  1. Must implement a client/server scheme. This allows them to be developed independently, and to replace them.
  2. It must be stateless (without state on the server). Therefore, the state must be persisted on the client. This improves the scalability, availability and performance of the application.
  3. Information must be given to the client (implicitly or explicitly) whether the content is cacheable. Thus, scalability and performance can be improved.
  4. It must have a uniform interface. Basically, a resource must be associated with a URI that allows access to its data.
  5. It must be designed as a layered system. The client cannot know specifically the architecture of the service or where the data resides, for example.
  6. Optionally, the client can request code from the server, to simplify its implementation (unusual).

Although not required, a RESTful service often uses HTTP as its protocol. In this case, the bodies of requests and responses are usually in XML or JSON format.

If we look at common CRUD operations, there is a convention of how to use HTTP methods using status codes 200, 201, 204, 400, 404 :

  • GET: read (idempotent).
  • POST: create (not cacheable).
  • PUT: update/replace.
  • DELETE: delete.
  • PATCH: partial modification.

Since the protocol is stateless, authentication/authorization must occur for each request. Best practices include using secure channels, and never exposing data in the URL. The use of Oauth is also recommended.

The use of tokens, or passwords, is common in authentication systems. The operation with token is as follows:

  • The user or client application accesses the authentication service.
  • If it is correct, the server generates a token that it sends to the client.
  • The user accesses the resources with their token.

Streaming API

A streaming protocol is precisely an inversion of RESTful. This is not a conversation. It's about opening a connection between a client and the API, where the client receives the nine results as they occur, in real time.

It is stateful in nature, as the API sends the results based on the customer's profile and/or the filtering rules you have set.

It is common to use the JSON format. In this case, the text format is used and messages can be delimited with line breaks.

An example is that of Twitter.