Sobre o REST

Antes de tudo precisamos entender que o REST (Representational state transfer) não é uma ferramenta, biblioteca nem mesmo um protocolo de comunicação.

Na verdade ele é um estilo arquitetural utilizado para comunicação entre sistemas. Com outras palavras, podemos dizer que é um conjunto de princípios e definições que definem uma forma padronizada para realizar essa comunicação.

Conceitos importantes

Ele é fortemente ancorado pelo protocolo HTTP, fazendo uso padronizado de URLs, verbos, status, cabeçalhos e tudo mais que o HTTP nos fornece.
Embora seja mais comum a utilização do formato JSON, ele não é uma restrição do REST, podendo ser utilizado XML, HTML, imagem, texto, etc.
Se trata de uma comunicação Cliente-Servidor. Isso quer dizer que de um lado o Servidor se comporta como provedor do serviço, continuamente disponibilizando o serviço a ser acessado. Já no outro lado, podemos ter 0, 1 ou vários Clientes conectando por demanda sempre que precisarem acessar algum dos recursos disponibilizados pelo Servidor.

O HTTP

Métodos (ou Verbos) HTTP:

Cada método possui uma finalidade específica que deve ser respeitada para deixar claro aos clientes qual o efeito esperado. Os métodos mais utilizados são:

GET: usado para busca de informações. Não deve alterar dados no servidor.
POST: usado para criação de recursos no servidor.
DELETE: usado para remoção de recursos existentes no servidor.
PUT: usado para substituição de recursos previamente criados no servidor.
PATCH: usado para atualização parcial de recursos previamente criados no servidor.

Status de retorno:

Da mesma forma que os métodos. Os status code existentes no HTTP são utilizados. Os status mais utilizados são:

Status de sucesso:

Ou seja, a operação foi realizada:

200: acompanhada de retorno de informações.
204: sem informações de retorno.
201: com a criação de informações.
202: de forma assíncrona, ou seja, foi recebida para processamento.

Status de erro de cliente:

Ou seja, a operação não foi realizada, e a responsabilidade provavelmente é do cliente:

400: e o motivo provavelmente está no corpo da requisição.
404: pois a informação solicitada não existe.
422: pois houve falha em uma validação de negócio.
401: por falta de autenticação.
403: por falta de permissão.

Status de erro de servidor:

Ou seja, a operação não foi realizada, e a responsabilidade provavelmente é do servidor:

500: e o motivo provavelmente está no retorno da requisição.
503: pois o serviço está indisponível.
502: pois um serviço necessário está retornando algo inesperado.
504: pois um serviço necessário está demorando para responder.

Exemplo prático

Uma requisição REST para gerenciar usuários:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


### Listar usuários
GET /api/usuarios
Accept: application/json

### Criar um usuário
POST /api/usuarios
Content-Type: application/json

{
    "nome": "João Silva",
    "email": "[email protected]"
}

### Resposta esperada (201 Created)
HTTP/1.1 201 Created
Location: /api/usuarios/1
Content-Type: application/json

{
    "id": 1,
    "nome": "João Silva",
    "email": "[email protected]"
}

### Buscar usuário específico
GET /api/usuarios/1
Accept: application/json

### Resposta esperada (200 OK)
HTTP/1.1 200 OK
Content-Type: application/json

{
    "id": 1,
    "nome": "João Silva",
    "email": "[email protected]"
}

### Remover usuário
DELETE /api/usuarios/1

### Resposta esperada (204 No Content)
HTTP/1.1 204 No Content

Conclusão

REST é o estilo arquitetural dominante para APIs web. Seguir seus princípios — uso correto dos verbos HTTP, statelessness, recursos bem definidos — garante APIs previsíveis, testáveis e de fácil manutenção.

Mais informações:

Gosta de vídeo?

REST // Dicionário do Programador - Código Fonte TV:

O QUE É UMA API RESTful NA PRÁTICA? MATURIDADE DE RICHARDSON - Michelli Brito:

Padrão REST: Entenda esse estilo arquitetural e aplique no seu projeto

Artigo que explora os fundamentos do padrão arquitetural REST, incluindo princípios chave, métodos HTTP, códigos de status e práticas recomendadas para projetar APIs RESTful de forma eficiente.