Definição de API Rest · Kvojps

Checklist para considerar uma API como Rest

Cliente/servidor: Separação entre as responsailidades de tela e processamento/armazenamento de dados.
Stateless: Cada requisição do cliente para o servidor deve conter todas as informações necessárias para o servidor entender e processar a solicitação. Ou seja, cada requisição é independente.
Cache: As respostas de uma API REST devem ser explicitamente rotuladas como cacheáveis ou não-cacheáveis. Quando uma resposta é cacheável, o cliente pode reutilizar os dados em requisições subsequentes, o que melhora a eficiência da rede, reduz a latência e diminui a carga nos servidores.
Interface uniforme:
- Identificação de recursos nas requisições: Cada recurso é identificado por um identificador único, geralmente um URI (Uniform Resource Identifier). Isso permite que o cliente referencie e acesse diretamente os recursos no servidor.
- Manipulação de recursos por meio de representações: Os recursos são manipulados por meio de suas representações, como JSON ou XML. O cliente interage com o servidor enviando representações de recursos que deseja criar, modificar ou excluir, e o servidor responde com representações dos recursos solicitados.
- Mensagens auto descritivas: Cada mensagem trocada entre cliente e servidor deve conter informações suficientes para descrever como processar a mensagem. Isso inclui informações sobre como interpretar a mensagem (tipos de mídia, esquemas de dados) e metadados relevantes (status de resposta, cabeçalhos HTTP). Mensagens auto-descritivas ajudam a tornar a comunicação mais clara e reduz a necessidade de documentação externa.
- HATEOAS (Hypermedia as the Engine of Application State): Este princípio garante que a interação com a API seja guiada por hypermedia, como links. Cada resposta do servidor deve incluir links para outras ações possíveis a partir da que foi executada, permitindo que o cliente navegue pela API dinamicamente. Isso proporciona uma maior flexibilidade e escalabilidade, pois o cliente não precisa conhecer a estrutura da API antecipadamente.
```
{
  "order_id": "123456",
  "status": "pending",
  "total_amount": 150.99,
  "links": [
    {
      "rel": "self",
      "href": "https://api.pizzashop.com/orders/123456"
    },
    {
      "rel": "cancel",
      "href": "https://api.pizzashop.com/orders/123456/cancel"
    },
    {
      "rel": "payment",
      "href": "https://api.pizzashop.com/orders/123456/payment"
    }
  ]
}
```
  - No exemplo acima, na lista de links, é possível ver o objeto que possui o campo rel com o valor self, que representa a URL atualmente em uso. Além disso, estão listadas outras URLs possíveis que podem ser acessadas a partir da URL atual.
Sistema em camadas: A arquitetura de um sistema REST pode ser composta por várias camadas, sem que os clientes (interfaces de usuário) precisem saber sobre a existência dessas camadas intermediárias.

Modelo de maturidade de Richardson

Nível 0 (The Swamp of POX): Neste nível, a API usa um único verbo HTTP que aceita qualquer tipo de solicitação. Por exemplo, o usar o verbo HTTP POST para todas as operações da API.
Nível 1 (Recursos): A API começa a ser dividida em recursos distintos, cada um representado por uma URL única. No entanto, ainda pode não utilizar todos os verbos HTTP corretamente. Por exemplo, a API pode usar apenas GET e POST, mas pelo menos há uma diferenciação clara entre diferentes tipos de dados e funcionalidades através de endpoints específicos.
Nível 2 (Verbos HTTP): Neste nível, a API usa adequadamente os verbos HTTP (GET, POST, PUT, DELETE, etc.) para realizar operações sobre os recursos. Além disso, os códigos de status HTTP são usados para indicar o resultado das operações (200 OK, 404 Not Found, 201 Created, etc.).
Nível 3 (HATEOAS): Como mencionado anteriormente, as respostas da API incluem links para outros recursos e ações possíveis, permitindo que os clientes naveguem pela API dinamicamente.