Entendendo HTTP e API's REST

Primeiramente, este post não tem como objetivo aprofundar nos assuntos tratados, é uma breve introdução sobre o que é uma API, o protocolo HTTP e o padrão REST, então de forma bem resumida:

• API: Interface que possibilita a comunicação entre plataformas através de padrões e protocolos.
• HTTP: Protocolo de transferência que permite obter recursos, como por exemplo, documentos HTML.
• REST: Estabelece um padrão para a implementação da API.

O que é uma API?

Um acrônimo do inglês (Application Programming Interface), por meio das APIs, é possível realizar a comunicação entre dois ou mais sistemas de forma facilitada, sem a necessidade de implementar totalmente um determinado código novamente, temos como exemplo uma API do sistema operacional, para um desenvolvedor criar um aplicativo de foto, ele pode simplesmente acessar a câmera através da API que o sistema disponibiliza ao invés de implementar todo o acesso ao hardware.

Como estamos nos referenciando a API para a web, podemos exemplificar a construção de um sistema web e um aplicativo mobile, é construído uma API independente da plataforma que irá consumir, e nas aplicações para cada plataforma fazemos apenas o consumo da mesma.

Entendendo o protocolo HTTP

O HTTP (Hypertext Transfer Protocol) é um protocolo que faz a especificação de como será a comunicação entre um navegador e um servidor web. Este protocolo funciona através do modelo computacional conhecido como cliente-servidor, on o cliente (navegador) estabelece a comunicação com o servidor e ambos passam a trocar informações entre si.

Request#

Os requests HTTP são compostos pelos seguintes blocos de informações:

• URL/endpoint → Identificação de recursos
• Query Params → Parâmetros na URL
• Método → Identificação de ação
• Headers → Informações adicionais
• Body → Corpo da mensagem

URL/endpoint e Query Params#

https://site.com/products?page=3&orderBy=name

URL Endpoint Query Params

Métodos (ou verbos)#

→ Principais métodos, também chamados de verbos HTTP:

• GET: Consulta de dados;
• POST: Criação de registros;
• PUT: Alteração de registros;
• DELETE: Remoção de registros.

Headers#

→ Usados para trocar informações adicionais entre client e server;

→ Existem headers pré definidos, porém, também podemos criar headers customizados;

• Nome e valor separados por dois pontos:

  content-type: application/json

• Case Insensitive:

  content-type: application/json

  authorization: Bearer usertoken

• Custom Headers (sempre começam com X):

  X-Org-ID: 1123

Body#

→ Apenas para requisições do tipo POST e PUT.

• JSON (JavaScript Object Notation)
• Multipart/form-data (Para arquivos binários, que não são aceitos no JSON)

{
	"user": {
		"id": 109,
		"name": "Gabriel",
		"roles": ["admin", "user"],
		"address": {
			"street": "My Street",
			"number": 720
		}
	}
}

Response#

Assim como as requests, elas também são formadas por blocos de informações:

• Headers → Informações adicionais
• Content Type → Tipo de conteúdo da resposta
• Status Code → Indica o que aconteceu com a request
• Body → Dados que foram requisitados

Como a maioria já foi tratado na request, veremos a seguir somente os Status Code

Códigos de status#

→ Categorizados pelo primeiro dígito:

• De 100-199: Respostas de informação;
• De 200-299: Respostas de sucesso;
• De 300-399: Redirecionamentos;
• De 400-499: Erros do cliente;
• De 500-599: Erros do servidor.

→ Principais códigos:

• 200: Ok;
• 201: Created;
• 204: No Content;
• 400: Bad Request;
• 401/403: Unauthorized;
• 404: Not Found;
• 405: Method Not Allowed;
• 409: Conflict;
• 500: Internal Server Error.

Exemplos#

Padrão REST

(Representational State Transfer)

→ Um padrão para construção de APIs;

→ Usa o protocolo HTTP;

→ Retorna uma representação do estado.

Nomes de Endpoints#

Utilizar o nome dos recursos sempre no plural

GET /products

GET /products/10

POST /products

PUT /products/10

DELETE /products/10

Representação do Estado#