De acordo com Roy Fielding, um dos idealizadores do modelo arquitetural REST, para que uma API seja considerada RESTful esta deve obrigatoriamente seguir um conjunto de constraints (regras) pré-definidas pelo próprio Roy. Tendo em vista a complexidade desse modelo, acabamos nos vendo presos em questões como “Isso não é possível!” ou até mesmo “Esse modelo é inalcançável!”, e seguir com a implementação dessas regras acaba sendo uma tarefa difícil e dolorosa.

Mas então, como prosseguir em casos assim?

Baseado nessas dores que Leonard Richardson propôs um novo modelo de maturidade dividido entre quatro níveis, visando alcançar o nível máximo REST, ou até melhor… a “glória” REST. O modelo de maturidade de Richardson

Certo, conte-me mais sobre esse modelo

O modelo desenvolvido por Leonard Richardson divide os principais elementos de REST em três importante passos:

• Recursos (resources)
• Verbos http (http verbs)
• Controles de hypermedia (hypermedia controls). 

Tenha em mente que este modelo é um facilitador enquanto construindo APIs, e que não é possível considerar uma API RESTful se os três níveis não forem alcançados.

Nível 0 – POX

Considerado o nível mais distante de uma API RESTful, aqui não se usa padrão para praticamente nada. Repare que o nome dos recursos (resources) não estão bem definidos, e estão sendo utilizados unicamente para invocar mecanismos remotos baseados em Remote Procedure Invocation. A troca mensagens neste nível pode até estar serializadas em formatos como XML, JSON ou texto,  porém, só isso não faz uma API ser RESTful.

REST é um conjunto de regras e padrões, enquanto RESTful é a implementação dessas regras em API.

Vamos imaginar uma interface de cadastro de clientes com suas operações CRUD (create, delete, update and delete). No modelo RPC POX, esta interface ficaria da seguinte forma:

RPC POX

Repare que o modelo acima, apesar de ser o modelo mais comum, faz uso apenas dos verbos GET e POST, e tem nomenclatura de recursos em um formato que não segue nenhum padrão. Mesmo que a resposta dessas requisições estejam no formato JSON, a implementação dos métodos foge do contexto de REST, logo … nada a ver com REST e muito distante de RESTful.

Um ponto importante a ser levado em consideração, independente do nível de maturidade alcançado, é a manipulação códigos de status HTTP. A manipulação incorreta de status impede que elementos de gateway e proxy trabalhem da maneira correta, podendo impactar negativamente a entrega de mensagens. Cadeias de códigos HTTP iniciadas com 1, 2, 3 representam mensagens de sucesso, enquanto 4 e 5 representam erros de client e server respectivamente.

Ficou curioso sobre código de status HTTP ? Acesse httpstatuses.com

Nível 1 – Recursos (Resources)

Neste nível, usa-se recursos (resources) como uma forma de modelar e organizar APIs. Necessariamente, não precisaremos conhecer as funcionalidade encapsulados em cada método, porém, devemos saber identificar visualmente o que cada recurso representa fazendo menção direta a um substantivo, preferencialmente no plural.

Vamos imaginar uma interface de clientes com operações CRUD, a mesma interface vista no nível anterior. Modelando o nome de recursos corretamente, farei uso apenas de alguns métodos HTTP, interagindo com os recursos individualmente.

REST

Nível 2 – Verbos HTTP (http verbs)

A partir desse momento, os verbos HTTP passam a ser usados com o verdadeiro propósito pelos quais foram criados. Os verbos mais utilizados são GET, POST, PUT e DELETE. O verbo GET, por padrão é utilizado para requisitar dados tem um papel essencial em APIs. Já POST, é comumente utilizado para gravar registros.

Por default, o GET é classificado como safe operation, pois não realiza nenhuma alteração ou altera o estado de um recursos quando executado. Isso permite invocar GET de forma segura quantas vezes forem necessárias.

Por um outro lado, o verbo POST é utilizado para adicionar novos registros (recursos), onde os dados da requisição vão encapsulados no corpo (body) da requisição.

POST /customer
{
  name: "ACME"
}

HTTP/1.1 201 Created
Location: /customer/1

• Entenda que “Location” é o local (uri) onde o recurso criado se encontra.
• Repare também que o status code na Start-Line está com 201, o que significa que o recurso foi criado com sucesso, esse é o tipo de preocupação que devemos ter no nível 2 no modelo de maturidade de Leonard Richardson.

Para a lista completa dos HTTP status codes disponíveis, acesso o Mozilla Developer Network – HTTP Status Code.

Nível 3 – HATEOAS

Também conhecido como Hypermedia as the Engine of Application State, Roy Fielding descreve HATEOAS como uma das premissas necessárias para considerar um API RESTful.

Tem como elemento principal a representação hypermedia, permitindo que um documento descreva seu estado atual, e o seu relacionamento com outros elementos ou futuros estados (delete, por exemplo). Entenda hypermedia como a capacidade de um recurso se relacionar com os demais em uma coleção

GET /customer/1
{
    "name": "ACME",
    "links": [ {
        "rel": "self",
        "href": "http://localhost:8080/customer/1"
    }, {
        "rel" : "delete",
        "href": "http://localhost:8080/customer/1"
    ]
}

Repare que customer possui hypermedia (links) que apontam para ele mesmo (estado atual) e delete (estado futuro). O ponto mais importante do hypermedia controls é a maneira que um resource deve ser manipulado é descrito, não tendo necessidade de adivinhações de quais operações estão de fato implementadas.

Rolou aquela dúvida ? Não esqueça de escrever abaixo nos comentários!

REFERÊNCIAS