Forem: Juan Cassiano

Modelo de Maturidade Richardson

Juan Cassiano — Wed, 07 Jun 2023 11:43:50 +0000

É muito comum ver APIs baseadas em arquitetura rest, mas seja por falta de conhecimento ou praticidade, não seguem à risca todas as restrições obrigatórias. A partir disso, temos um mapeamento, feito por Leonard Richardson, chamado Modelo de Maturidade de Richardson.

Nível 0 → Plain Old XML (POX). Nesse nível, o protocolo HTTP é utilizado apenas como transporte de dados, sem a utilização correta dos verbos e status. Geralmente, há apenas um único endpoint. Apesar do nome XML, também é possível utilizar JSON.

POST /salvarCliente 
    <Cliente>
         <Nome>Manoel da Silva</Nome>
         ...
  </Cliente>

Nesse nível, apenas um verbo é utilizado como tipo de operação: o POST. Todas as URLs criadas para obter dados, atualizar dados, inserir e deletar são chamadas utilizando o POST. Outro ponto interessante nesse nível é que há apenas uma única URL para acesso à API. Portanto, caso seja feita uma requisição para obter todos os usuários de um aplicativo, teríamos o seguinte exemplo:

Da mesma forma, caso a requisição realizada para essa API seja para inserir um novo cliente, a URL utilizada seria a mesma, alterando alguns parâmetros. No desenvolvimento, é responsabilidade do programador garantir que os processos requisitados sejam corretamente manipulados. Por exemplo, a URL para inserir usuários seria:

O problema de uma API nesse nível é que, para operações simples, é necessário criar muita documentação, pois além da falta de clareza sobre a estrutura e suas relações, os comandos são personalizados na URL.

Um outro problema constantemente encontrado, é a manipulação incorreta dos códigos de resposta do HTTP. Códigos e mensagens de erros são frequentemente manipuladas nas mensagens geradas pela aplicação, o que impede que elementos de gateway e proxy trabalhem de forma adequada.

GET /buscarCliente/1
HTTP/1.1 200 OK
<buscarCliente>
<status>CLIENTE NÃO ENCONTRADO</status> <codigo>404</codigo>
<buscarCliente>

Nivel 1 → As requisições são feitas para URIs que identificam recursos, porém, os verbos e códigos de status não são utilizados corretamente. O corpo e a resposta também são semelhantes. O tipo de procedimento ainda é definido no corpo.

Nesse nível, ainda é utilizado apenas um tipo de operação: o POST. Também é importante garantir que, nesse nível, os nomes dos recursos estejam no plural, sem letras maiúsculas e utilizando hífens para separação.

POST /clientes 
    <Cliente>
         <Nome>Manoel da Silva</Nome>
         ...
  </Cliente>

Nível 2 → Introduz o uso de verbos de acordo com a semântica e o protocolo HTTP. Os códigos são utilizados corretamente. Esse é o nível da maioria das aplicações do mercado. O formato do payload (XML/JSON) não interfere no nível.

POST /cliente
    <Cliente>
    <Nome>Manoel da Silva</Nome>
    ...
</Cliente>

Dessa forma, a API fica muito mais legível para manutenção, reduzindo seu custo e tornando-a mais fácil de ser consumida. Já se sabe, por exemplo, que ao fazer um GET é esperado o retorno de dados, e isso ajuda inclusive na performance da transferência de dados.

201 Created
 Location: /cliente/1

Nível 3 → HATEOAS (Hypertext as the engine of application state). Indica quais são as ações possíveis após uma requisição, juntamente com as URIs correspondentes. A ideia é ajudar os consumidores da API a descobrirem as funcionalidades e o fluxo da aplicação. A API retorna os links interligando o recurso com outros (ou até mesmo com ele mesmo), e existem especificações de como implementar os links com JSON.

GET /cliente/1
          HTTP/1.1 200 OK
          <Cliente>
              <Id>1</Id>
              <Nome>Manoel da Silva</Nome>
              <link rel="deletar" href="/cliente/1" />
              <link rel="notificar" href="/cliente/1/notificacao" />
          </Cliente>

Analisando todos os níveis de maturidade existentes e aplicando todas as práticas para atingi-los, é garantido que, ao construir uma API no nível 3 de maturidade, ela estará organizada, com os endpoints fáceis de serem compreendidos, recursos fáceis de serem encontrados, escalabilidade garantida e uma autodocumentação para seus recursos. Isso facilitará a vida dos usuários que irão consumi-la e dos desenvolvedores que a manterão.

A implementação do HATEOAS na API traz diversos benefícios:

Descoberta dinâmica de recursos: Com o HATEOAS, um cliente da API não precisa ter conhecimento prévio de todos os endpoints e recursos disponíveis. Em vez disso, ele pode começar a partir de um ponto de entrada conhecido (por exemplo, a URL raiz da API) e, a partir da resposta recebida, descobrir os recursos disponíveis e os links relacionados a eles. Isso permite uma experiência mais flexível e adaptável, uma vez que as alterações na API não exigem modificações nos clientes existentes.
Navegação simplificada: Os links fornecidos pela API permitem que os clientes naveguem facilmente entre os recursos relacionados, sem a necessidade de construir manualmente as URLs correspondentes. Por exemplo, um cliente pode obter um recurso "Cliente" e, a partir dos links fornecidos, navegar para a página de detalhes desse cliente, sua lista de pedidos ou qualquer outro recurso relacionado. Isso simplifica a interação com a API e reduz a carga cognitiva do desenvolvedor.
Evolução da API: Com o HATEOAS, a API pode evoluir e adicionar novos recursos sem interromper os clientes existentes. Se um novo recurso é introduzido e vinculado a partir das respostas da API, os clientes que entendem o padrão HATEOAS podem descobri-lo e começar a usá-lo. Isso promove uma arquitetura mais flexível e extensível, onde os clientes podem se adaptar a mudanças na API de forma dinâmica.

Exemplo: Suponha que uma API de e-commerce esteja retornando a seguinte resposta JSON para um recurso "Produto":

{
  "id": 123,
  "nome": "Camiseta",
  "preco": 29.99,
  "links": [
    {
      "rel": "self",
      "href": "/produtos/123"
    },
    {
      "rel": "pedidos",
      "href": "/produtos/123/pedidos"
    },
    {
      "rel": "avaliacoes",
      "href": "/produtos/123/avaliacoes"
    }
  ]
}

Nesse exemplo, os links são fornecidos no campo "links". O link "self" aponta para o próprio recurso "Produto" e os links "pedidos" e "avaliacoes" apontam para recursos relacionados. Um cliente que recebe essa resposta pode utilizar os links para navegar para esses recursos relacionados sem a necessidade de construir manualmente as URLs.

Portanto, o HATEOAS promove uma abordagem mais dinâmica e exploratória da API, permitindo que os clientes descubram recursos e interajam com eles de forma mais flexível e orientada por hipertexto.

É importante destacar que a adoção do HATEOAS pode adicionar complexidade à implementação da API e pode não ser necessário ou adequado para todos os casos de uso. Nem todos os projetos precisam ou se beneficiam de todos os níveis de maturidade. Portanto, é fundamental avaliar cuidadosamente as necessidades e metas do projeto antes de decidir em qual nível se concentrar.

Richardson Maturity Model

RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1

RFC 7231: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content

RESTful Web APIs: Services for a Changing World

REST in Practice: Hypermedia and Systems Architecture

Idempotência em Requisições HTTP

Juan Cassiano — Mon, 29 May 2023 23:39:13 +0000

A noção de idempotência vem da matemática. Multiplicar um número por zero é uma
operação idempotente. 5 × 0 é zero, mas 5 × 0 × 0 também é zero. Depois de multiplicar um
número por zero, você pode continuar multiplicando-o por zero indefinidamente e obter o mesmo resultado: 0.

A idempotência é uma propriedade importante de algumas operações HTTP que garante que a mesma operação pode ser executada várias vezes sem alterar o resultado final ou causar efeitos colaterais indesejados, independente do número de vezes que é chamada, isso é importante em situações em que uma operação pode ser executada várias vezes, como em caso de falha de rede ou retry automático de uma operação não concluída.

Safe Methods:

Os métodos de solicitação são considerados "seguros" se sua semântica definida for essencialmente somente leitura, ou seja, o cliente não solicita e não espera qualquer mudança de estado no servidor de origem como resultado de aplicar um método seguro a um recurso de destino. Da mesma forma, razoável não se espera que o uso de um método seguro cause qualquer dano, perda de propriedade ou carga incomum no servidor de origem.

Exemplos de métodos seguros:

GET → É usado para obter informações sobre um recurso em um servidor. Quando um cliente faz uma solicitação GET, ele espera receber informações sobre o recurso solicitado, mas não espera que a solicitação cause qualquer mudança de estado no servidor. Além disso, é razoável esperar que o uso do método GET não cause nenhum dano, perda de propriedade ou carga incomum no servidor de origem.


URL: https://api.exemplo.com/usuarios/123
Método: GET

Status de Resposta: 200 OK
Conteúdo JSON da Resposta:
{
  "id": 123,
  "nome": "João Silva",
  "email": "joao.silva@exemplo.com",
  "idade": 35,
  "cidade": "Rio de Janeiro"
}

HEAD → É usado para obter apenas os cabeçalhos de uma resposta HTTP, permitindo que o cliente verifique informações como o código de status, os cabeçalhos de resposta e a data da última modificação de um recurso. Ex: Um cliente pode enviar uma solicitação HEAD para um recurso de imagem para verificar seu tamanho, tipo de conteúdo e data da última modificação, sem receber o próprio conteúdo da imagem.

HEAD /downloads/video1.mpeg HTTP/1.0

OPTIONS →É usado para obter informações sobre as opções de comunicação disponíveis para um determinado recurso ou servidor. Ele retorna os métodos HTTP suportados pelo servidor, cabeçalhos permitidos, entre outras informações relevantes. Ex: Um cliente pode enviar uma solicitação OPTIONS para um servidor de API REST para descobrir quais métodos são permitidos para um determinado recurso, como GET, POST, PUT ou DELETE.

OPTIONS /download.php

Outros métodos idempotêntes:

DELETE → Obviamente não é um método seguro (Safe Method), porém enviar uma solicitação DELETE é muito diferente de não enviar uma solicitação DELETE. Mas o método DELETE tem outra propriedade muito importante: Ele é idempotente.
Depois de excluir um recurso, ele desaparece. O estado do recurso mudou permanentemente. Você pode enviar outra solicitação DELETE e você pode obter um erro 404, mas o estado do recurso é exatamente como era após o primeiro pedido. O recurso ainda está desaparecido. Isso é idempotência. Enviar uma solicitação duas vezes tem o mesmo efeito no estado do recurso que enviá-la uma vez. A idempotência é um recurso útil, porque a Internet não é uma rede confiável. Suponha você envia uma solicitação DELETE e sua conexão atinge o tempo limite. Você nunca obteve uma resposta, então você não sabe se o DELETE passou. Você pode simplesmente enviar essa solicitação DELETE novamente e continue tentando até obter uma resposta. Nada extra acontecerá se um DELETE passa duas vezes em vez de uma vez. HTTP DELETE efetivamente multiplica um recurso por zero. Multiplicar por 1 é uma operação segura, da mesma forma que o HTTP GET deve ser seguro. Você pode multiplique um número por 1 durante todo o dia e nada mudará. Toda operação segura é também idempotente.

URL: https://api.exemplo.com/usuarios/123
Método: DELETE

PUT → PUT é idempotente, assim como DELETE. Se você enviar a mesma solicitação PUT 10 vezes, o resultado é o mesmo como se você tivesse enviado apenas uma vez. O cliente também pode usar PUT para criar um novo recurso, se souber a URL onde o novo recurso deve viver.

URL: https://api.example.com/usuarios/123
Método: PUT
Conteúdo JSON da solicitação:
{
    "nome": "John Doe",
  "email": "johndoe@example.com",
  "idade": 30
}

Observe que PUT é uma operação idempotente mesmo quando você o usa para criar um novo recurso. Se enviar essa solicitação PUT cinco vezes, ela não será criada cinco postagens com o mesmo texto (da mesma forma que cinco solicitações POST podem).

Como a definição de seguro, a propriedade idempotente só se aplica a o que foi solicitado pelo usuário. Um servidor é livre para registrar cada um separadamente, reter um histórico de controle de revisão ou implementar outros efeitos colaterais não idempotentes para cada solicitação idempotente.

Métodos idempotentes são diferenciados porque a requisição pode ser repetida automaticamente se ocorrer uma falha de comunicação antes do cliente ser capaz de ler a resposta do servidor.

Para garantir que as operações na API sejam idempotentes, é importante que os recursos e endpoints sejam projetados de maneira apropriada, por exemplo, com o uso de identificadores únicos de recursos, como IDs, e o gerenciamento de transações e commits adequados. Isso ajuda a garantir que as operações possam ser executadas várias vezes sem causar problemas indesejados, como a criação de recursos duplicados ou inconsistências de dados.

E Quanto ao método POST e PATCH?

O método POST é não idempotente, pois cada chamada cria um novo recurso com um identificador único. Se um cliente enviar várias solicitações POST com os mesmos dados, serão criados vários recursos diferentes no servidor.

O método POST é não seguro, pois cria um novo recurso no servidor. A criação desse recurso pode ter efeitos colaterais, como enviar notificações, acionar processos de negócios, registrar informações no servidor, entre outros.

O método PATCH é usado para fazer atualizações parciais em um recurso existente. Em vez de substituir completamente o recurso, o PATCH permite que apenas as alterações específicas sejam aplicadas. No entanto, o método PATCH não é idempotente nem seguro.

URL: https://api.exemplo.com/usuarios/123
Método: PATCH
Conteúdo JSON da solicitação:
{
  "idade": 25
}

Nesse exemplo, a solicitação PATCH é usada para adicionar um campo "idade" a um usuário existente. Se o campo "idade" já estiver presente, a chamada PATCH adicionará um novo valor ao campo. Cada chamada PATCH subsequente com o mesmo conteúdo JSON resultará em alterações adicionais no campo "age" do recurso.

Um método não idempotente é aquele em que a execução repetida da mesma operação pode ter efeitos diferentes no servidor. Cada chamada adicional a um método não idempotente pode resultar em alterações de estado ou efeitos colaterais diferentes. Portanto, a mesma solicitação enviada várias vezes pode levar a resultados diferentes.

Um método não seguro é aquele que pode causar alterações no estado do servidor ou ter efeitos colaterais indesejados. Enquanto um método seguro é apenas leitura e não deve causar alterações, um método não seguro pode alterar o estado do servidor ou executar ações que afetam o ambiente.

Portanto, métodos não idempotentes e não seguros, como POST e PATCH, podem ter efeitos diferentes em cada chamada adicional e podem causar alterações no estado do servidor ou efeitos colaterais indesejados.

Método HTTP	IDEMPOTÊNCIA	MÉTODO SEGURO
GET	SIM	SIM
HEAD	SIM	SIM
PUT	SIM	NÃO
DELETE	SIM	NÃO
POST	NÃO	NÃO
PATCH	NÃO	NÃO

Documentação: RFC7231 - Seção 4.2.2

RFC ft-ietf-httpbis-p2-semantics: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content

Livro:

Amundsen, Mike Richardson, Leonard Ruby, Sam - RESTful Web APIs-O'Reilly Media (2015)

RESTful Web APIs: Services for a Changing World