Níveis de maturidade de uma API REST (Glória do REST)

O nível de maturidade de uma API REST é uma medida da sua capacidade de seguir os princípios REST, fornecer uma interface fácil de usar e adaptável e permitir que os desenvolvedores aproveitem as vantagens do protocolo HTTP. Ao seguir esses níveis de maturidade, as APIs REST podem ser facilmente consumidas por uma ampla gama de aplicativos, aumentando sua usabilidade e facilitando a adoção por desenvolvedores e empresas.

A maturidade da API REST é geralmente classificada em quatro níveis, conforme proposto por Leonard Richardson e Sam Ruby em seu livro "RESTful Web Services":

Nível 0: Serviço web

Um serviço web no nível 0 não possui padronização.

Ele é basicamente uma coleção de operações remotas expostas por meio de uma interface SOAP (Simple Object Access Protocol) ou WSDL (Web Services Description Language), sem qualquer uso do protocolo HTTP.

Nesse nível, as operações são realizadas usando um único verbo HTTP POST, ou seja, todas as URLs criadas para realizar ações de obter, atualizar, inserir e deletar dados são chamadas usando o POST, portanto, a API não usa recursos ou URIs.

Nível 1: Recursos

No nível 1, a API começa a expor seus recursos usando URIs para cada recurso, porém de forma padronizada, ou seja, os nomes dos recursos devem estar no plural e sem letras maiúsculas.

No exemplo do crud de products, os recursos seriam identificados pelo substantivo “products”.

Um detalhe interessante é que, no nível 1, já utilizamos os verbos HTTP de forma correta, embora ainda não esteja utilizando-os de maneira semântica, como ocorre no nível 2.

Nível 2: Verbos HTTP

No nível 2, a API começa a usar os verbos HTTP de maneira semântica para manipular seus recursos.

Cada operação é realizada usando um verbo HTTP específico, como GET, POST, PUT e DELETE. Isso torna a API mais fácil de usar e entender, e permite que os desenvolvedores aproveitem os recursos do protocolo HTTP.

Hoje, se você trabalha com os verbos, organizando o padrão das suas URLs baseado no recurso, então você está trabalhando com REST no nível 2.

Nível 3: HATEOAS

No nível 3, a API adota o conceito de HATEOAS (Hypermedia as the Engine of Application State), onde cada recurso da API contém links para outros recursos relacionados. Isso permite que os clientes da API naveguem pelos recursos e descubram as possíveis operações que podem ser realizadas em cada um deles.

Nesse nível de maturidade, parte do princípio de que o usuário não deve conhecer todas as rotas da API com antecedência, mas enquanto navega pela mesma, pode ir conhecendo e sabendo o que ela pode fazer.

O HATEOAS torna a API mais flexível e adaptável, permitindo que ela evolua com as necessidades dos usuários.

Qual nível de maturidade construir sua API?

O nível de maturidade em que construir uma API REST depende das necessidades dos usuários e dos objetivos do projeto. Embora o nível 3 (HATEOAS) seja considerado o estado ideal para uma API REST, nem todas as APIs precisam atingir esse nível de maturidade.

Por exemplo, se a API for usada internamente por uma única equipe, o nível 2 pode ser suficiente para atender às necessidades dos usuários e oferecer uma interface fácil de usar. Por outro lado, se a API for pública e precisar suportar um grande número de clientes diferentes, o nível 3 pode ser necessário para fornecer a flexibilidade e adaptabilidade necessárias.