REST – Richardson Maturity Model

Introdução

Falando em REST é frequente escutarmos o termo Richardson Maturity Model. Termo criado por Leonard Richardson descreve os requisitos necessários para a criação de um API REST bem estruturada/desenhada. Nada mais é que uma referência de boas práticas para criação de APIs de qualidade.

O Richardson Maturity Model descreve quatro níveis (0-3). Quanto mais sua API adere a esse níveis, melhor “pontuação” sua API ganha. Ao alcançar o nível máximo, sua API alcança o que é chamado de Glory of REST. Veremos abaixo cada um dos níveis:

Level 0

No nível 0 utiliza-se o protocolo HTTP como camada de transporte para interações remotas. Usa-se o HTTP apenas como uma forma de RPC (Remote Procedure Call). É como se estivéssemos chamando funções, porém através do uso do HTTP. Todos serviços são centralizados em um único endpoint, ou seja, todas as solicitações são feitas em uma única URI. Exemplo de uma chamada RPC usando HTTP:

http://www.example.net/servicos?method=album.musicas.search&tags=rock.

Porém explora-se muito pouco dos recursos disponíveis do HTTP. Nada de verbos HTTP, ou de permitir o retorno de múltiplos tipos de media, controles de hipermídia (links), uso dos headers e códigos de status de resposta, etc. No máximo usa-se POST para inserir/editar/deletar recursos e GET para consultar.

Level 1 – Recursos

A principal evolução em relação ao nível 0 é o uso de URIs individuais para cada Recurso (Resource). Ao invés de centralizar todas chamadas em /servicos por exemplo, usá-se /usuarios, /livros, /autores, etc.

Também é usado URIs únicas para acesso a itens individuais de recursos, como por exemplo: /usuarios/joao, /livros/1234, /autores/eduardo, etc. Neste nível ainda não é explorado verbos HTTP, múltiplos tipos de retorno de media, links entre serviços, etc.

Level 2 – Verbos HTTP

Neste nível é considerado as APIs que seguem as práticas dos níveis 0 e 1 e acrescenta o uso dos Verbos, headers e código de status do protocolo HTTP. É comum usar os verbos GET (operações que não modificam recursos), POST (inserções de novos recursos), PUT (atualização completa do recurso), PATCH (atualização parcial de um recurso) e DELETE (exclusão de recursos).

Os artigos Aplicação REST simples com Silex, parte I e Aplicação REST simples com Silex, parte II mostram como implementar um simples CRUD em REST explorando os verbos HTTP.

Neste nível também se faz o uso apropriado de status codes na construção das respostas das requisições: 200 OK, 201 Created, 204 No Content, 401 Unauthorized, 403 Forbidden, 404 Not Found, etc. Sugiro consultar os links HTTP Status Codes – REST API Tutorial, HTTP Response Status Codes – YDN e Common REST API Error Codes – MSDN – Microsoft como boas referências para utilizar os status codes de forma apropriada em sua API REST.

Também é apropriado para este nível usar headers HTTP para algumas finalidades. Por exemplo, Authorization para autenticação básica. Accept que permite o consumidor da API indicar qual formato de dados ele sabe trabalhar. Content-Type para informar o formato de conteúdo que esta sendo apresentado para o cliente, entre outros como Location, User-Agent, Last-Modified, ETag, Content-Length, etc.

Para ilustrar mais sobre esse assunto veja esse outro artigo meu RESTful & PHP Formatos de Representação que mostra como você pode usar o header Accept, informado pelo consumidor da API, para decidir o formato do recurso que deseja receber.

Level 3 – Controles de Hipermídia

Ao considerar os níveis anteriores do Richardson Maturity Model, você já atingiu uma excelente qualidade referente as características arquiteturais e de usabilidade da sua API. Porém ainda existe mais uma coisa que você pode fazer para tornar sua API ainda mais usável e melhor: Utilizar controles de Hipermídia.

Controles de hipermídia nada mais são do que o uso de Links para outros recursos e coleções dentro de sua API. É uma excelente forma de dizer ao consumidor de sua API o que ele pode fazer em seguida. É importante que os links sejam relacionados ao recurso que esta sendo consumido no momento. Por exemplo, ao trazer o conteúdo de um recurso “música”, você pode trazer um link para o “álbum” que aquela música pertence, ou informar um link para todas as “reviews” realizadas nesta música pelos usuários do sistema, entre outros. Este tipo de abordagem acaba criando uma documentação “natural” de sua API indicando como os recursos de relacionam.

Referências

http://martinfowler.com/articles/richardsonMaturityModel.html
http://restcookbook.com/Miscellaneous/richardsonmaturitymodel/
https://apigility.org/documentation/api-primer/what-is-an-api

Comments

  1. Reply

    • By Douglas V. Pasqua

      Reply

      • Reply

        • By Douglas V. Pasqua

          Reply

Deixe um comentário

Follow

Get every new post on this blog delivered to your Inbox.

Join other followers: