O que é RESTful API: guia dos 4 níveis

Uma RESTful API só existe quando a resposta carrega controles de hipermídia que permitem ao cliente navegar sozinho. O modelo de maturidade de Richardson descreve quatro níveis, e a maioria das APIs que se dizem REST para no nível 2, muito antes de chegar lá. Sem links navegáveis, o máximo que você tem é uma API HTTP com JSON.

RESTful API: o que o modelo de maturidade de Richardson exige

Uma RESTful API é uma API guiada por controles de hipermídia, e o modelo de maturidade de Richardson mede o quanto uma API se aproxima disso em quatro níveis. Só o nível 3 satisfaz REST, porque só ele entrega links que permitem ao cliente navegar sem conhecer as URLs de antemão.

O modelo foi proposto por Leonard Richardson em 2008, segundo a explicação do canal Full Cycle no vídeo "Se a sua API Rest não aplica este princípio, ela não é REST", publicado em 29 de novembro de 2024. O termo REST vem de Representational State Transfer, ou transferência de estado representacional, um estilo arquitetural descrito por Roy Fielding na dissertação de doutorado dele em 2000.

Fielding trabalhou na ideia desde 1994, participou do desenvolvimento do protocolo HTTP e atuou nos grupos de trabalho da W3C e da IETF, que definem padrões da web. A dissertação estabeleceu princípios, não uma régua para julgar APIs. O próprio Fielding reconheceu essa lacuna, e a intenção era manter o foco nos princípios em vez de criar um teste de conformidade.

O modelo de Richardson virou a régua informal que a dissertação não ofereceu. Ele separa quatro níveis, e a passagem de um para outro troca liberdade por previsibilidade. A tabela abaixo resume o que cada nível acrescenta e onde a maioria das APIs estaciona.

Os 4 níveis do modelo de maturidade de Richardson

Os quatro níveis de maturidade de Richardson vão do pântano dos POX, sem padrão algum, até o nível 3, onde a resposta traz links que guiam o cliente. Cada nível resolve um problema diferente, e avançar não depende de tecnologia nova, apenas de disciplina de projeto.

Nível	O que define	O que ainda falta
0 — Pântano dos POX	Um único endpoint HTTP, geralmente POST, carregando tudo	Recursos, verbos, hipermídia
1 — Recursos	URIs padronizadas, como /products/42	Verbos HTTP e hipermídia
2 — Verbos HTTP	Métodos combinados com recursos, como POST /customers	Controles de hipermídia
3 — Controles de hipermídia	Respostas com links navegáveis e recursos autodescritivos	Nada; é o patamar RESTful

No nível 0, tudo trafega por um endereço só e o cliente sabe exatamente o que enviar porque combinaram antes. Não há padronização de URI, de verbo nem de resposta. O vídeo chama esse uso de freestyle, e o resultado é uma API que funciona, mas não é REST.

No nível 1, a equipe define recursos e padroniza as URIs. O que está exposto passa a ter endereço previsível, mesmo que os verbos ainda não estejam combinados com esses endereços.

No nível 2, verbo e recurso passam a trabalhar juntos: criar um cliente vira POST /customers, e não uma URL como /bar/customers com semântica inventada. Essa é a parada da maioria das APIs que se dizem REST.

No nível 3, a resposta carrega links. Ao criar um produto, a API devolve os dados e também as operações possíveis a partir dali. É esse acréscimo que torna a API navegável e autodescritiva.

Por que controles de hipermídia separam nível 2 de RESTful

Controles de hipermídia são links e metadados na resposta que dizem ao cliente o que ele pode fazer em seguida. Sem eles, o cliente precisa conhecer cada URL e cada verbo de antemão, o que contraria a ideia de descoberta que sustenta a web.

O vídeo vai além: não existe RESTful sem controles de hipermídia. Uma API que para no nível 2 pode ser bem projetada, mas pertence à categoria HTTP com JSON, não à categoria REST. A etiqueta RESTful fica reservada ao nível 3.

A comparação com um site ajuda. Numa página HTML, você não decora endereços, apenas clica em links e preenche formulários. A hipermídia está em cada link, botão, imagem, vídeo e formulário. Uma API RESTful transporta essa mesma ideia para respostas de dados.

O resultado prático é um cliente capaz de descobrir recursos, métodos, status codes e media types sem documentação externa. A documentação passa a viver na própria API, e o cliente segue os links em vez de seguir um contrato fixo de URLs.

Como fica uma resposta no nível 3 na prática

No nível 3, cada resposta inclui uma seção de links que descreve o próprio recurso e as operações seguintes. Ao acessar a raiz da API, o cliente recebe os recursos disponíveis e pode navegar a partir dali sem conhecimento prévio.

O vídeo usa uma API de pagamentos como exemplo. A raiz devolve links como o self, que aponta para o endereço recém-acessado, além dos recursos de pagamentos, clientes e faturas. Cada link informa a descrição e o verbo HTTP que deve ser usado.

Ao listar /payments, a resposta traz os pagamentos em JSON e, na parte de links, um caminho de criação com o verbo exigido. Ao criar um pagamento com POST e os dados pertinentes, a resposta devolve o pagamento criado, os dados, e links para consultar ou cancelar aquele pagamento específico.

O cliente percorre a API como percorreria um site, sem saber de antemão quais recursos existem ou quais verbos usar. O servidor define o próximo estado possível, e o cliente apenas segue a indicação recebida.

Formatos de representação: JSON, XML e media types

REST não exige JSON. O formato da representação é escolha do servidor e do cliente, negociada por media types, e essa separação é o que permite manter a mesma URI enquanto o formato muda.

Nos primeiros anos de REST, XML era o formato dominante, em parte por causa de SOAP e XML-RPC, que usavam XML como base. Com a popularização do JavaScript e do Ajax, acrônimo de Asynchronous JavaScript and XML, o JSON ganhou espaço e acabou tomando o lugar do XML, mesmo o nome do Ajax continuando a citar XML.

A negociação acontece por cabeçalhos. No pedido, o cliente envia Accept para declarar o que aceita receber; no envio de dados, usa Content-Type para declarar o que está mandando. A resposta informa o formato que está devolvendo.

Um exemplo de media type de fornecedor citado no vídeo é application/vnd.minhaapi.v1+json, em que vnd indica vendor, v1 indica a versão e json indica o formato. O nome do recurso permanece o mesmo, e a versão viaja no cabeçalho, não na URL.

Benefícios reais dos controles de hipermídia

Controles de hipermídia trazem quatro ganhos concretos: desacoplamento entre cliente e servidor, descoberta de recursos, manutenção mais barata e versionamento sem quebrar o cliente. O ponto de partida é a URI deixar de ser contrato.

Desacoplamento significa que o frontend não precisa conhecer URIs e métodos. Ele segue os links disponíveis. Se a URI de um recurso mudar, o cliente não quebra, porque ele nunca dependeu daquele endereço fixo.

Descoberta significa encontrar recursos que o cliente não sabia que existiam, apenas navegando pelas respostas. A manutenção melhora pelo mesmo motivo: mudanças de endereço passam a ser invisíveis para quem consome.

O versionamento usa media types para indicar qual versão da API o cliente quer. O recurso de pagamentos continua com o mesmo endereço, e um Accept diferente pede CSV ou PDF. O nome do recurso permanece atemporal, e os formatos mudam nos cabeçalhos.

Quando uma API pode parar no nível 2 sem culpa

Parar no nível 2 não é erro de engenharia. É uma decisão de escopo, e a API deixa de ser RESTful apenas como consequência, não como defeito.

O vídeo é explícito: não há nada de errado em criar uma API sem implementar todos os princípios REST. A maturidade é gradual e passa pelo conhecimento da equipe, da empresa, do projeto e do produto. APIs com escopo pequeno podem não precisar de controles de hipermídia.

O problema começa na etiqueta. Chamar de RESTful uma API que não navega por links distorce a conversa e cria expectativa errada. O caminho mais honesto é saber em qual nível a API está e decidir conscientemente se vale subir.

Essa visão evita o dogmatismo. O objetivo não é forçar toda API ao nível 3, e sim reconhecer o custo e o benefício de cada nível antes de escolher onde parar.

Fielding já reclamava disso em 2008

Roy Fielding publicou em 2008 uma reclamação sobre APIs que se dizem REST sem hipermídia, no mesmo ano em que o modelo de Richardson apareceu. O problema não é novo e não nasceu com a popularização do JSON.

Segundo o vídeo, Fielding afirmava que muitas dessas APIs estavam mais para RPC ou para algo que ele descrevia como Restless. Para ele, uma API só merece a etiqueta se implementar os controles de hipermídia e se guiar por esse princípio.

O termo REST sofreu o que o vídeo descreve como efeito do próprio sucesso. Foi reduzido a duas coisas, HTTP e JSON, e perdeu a parte que o distinguia de qualquer API web comum.

Vale notar que hipertexto não é hipermídia em qualquer formato. A restrição de Fielding fala de hipermídia como o mecanismo de mudança de estado da aplicação, e é essa função que os links cumprem numa resposta de API.

FAQ sobre RESTful API e o modelo de Richardson

• O que é uma RESTful API? É uma API que aplica os princípios REST de forma integral, incluindo controles de hipermídia nas respostas. Isso corresponde ao nível 3 do modelo de maturidade de Richardson. Sem links navegáveis, a API usa HTTP e JSON, mas não é RESTful.

• Qual é a diferença entre REST e RESTful? REST é o estilo arquitetural descrito por Roy Fielding em 2000. RESTful descreve uma API que segue esse estilo por completo. O sufixo indica conformidade com os princípios, não apenas uso do protocolo HTTP.

• O que é o modelo de maturidade de Richardson? É uma escala de quatro níveis proposta por Leonard Richardson em 2008 para medir o quanto uma API se aproxima de REST. Os níveis vão do pântano dos POX até os controles de hipermídia, e só o nível 3 satisfaz REST.

• Quantos níveis tem o modelo de maturidade de Richardson? São quatro: nível 0, o pântano dos POX; nível 1, com recursos padronizados; nível 2, com verbos HTTP combinados aos recursos; e nível 3, com controles de hipermídia. A maioria das APIs para no nível 2.

• Por que a maioria das APIs para no nível 2? Porque recursos padronizados e verbos HTTP corretos já resolvem a maior parte dos problemas do dia a dia, e adicionar hipermídia exige mais trabalho de modelagem. Muitas equipes consideram o nível 2 suficiente e seguem adiante.

• RESTful API precisa usar JSON? Não. A representação pode ser JSON, XML, CSV, PDF ou outro formato negociado por media types. O vídeo cita application/vnd.minhaapi.v1+json como exemplo de media type de fornecedor com versão embutida. A URI permanece a mesma quando o formato muda.

• O que são controles de hipermídia? São links e metadados incluídos nas respostas que mostram ao cliente quais operações são possíveis a partir do estado atual. Eles tornam a API autodescritiva e permitem que o cliente navegue sem conhecer as URLs de antemão.

• Uma API pode ser chamada de REST se não tiver hipermídia? Não. O vídeo é direto nesse ponto: sem controles de hipermídia, a API não é RESTful, mesmo que use HTTP e JSON corretamente. Ela pode ser uma boa API HTTP, e isso não é demérito, desde que a etiqueta seja usada com precisão.

• Como versionar uma API RESTful sem quebrar o cliente? Use media types nos cabeçalhos Accept e Content-Type para indicar a versão desejada. O nome do recurso permanece estável, e o cliente escolhe a representação sem alterar a URI.

• Vale a pena chegar ao nível 3 do modelo de Richardson? Depende do escopo. APIs com muitos consumidores e evolução frequente ganham com desacoplamento e descoberta. APIs pequenas e estáveis podem operar bem no nível 2, desde que a equipe saiba onde está.

Do vídeo ao artigo com Skala Blog

A discussão sobre níveis de maturidade costuma ficar presa em vídeos e conversas. Quem tem uma explicação boa sobre arquitetura, uma entrevista ou uma aula gravada normalmente não tem tempo de transformar aquele material em texto. O Skala Blog resolve essa etapa: você cola o link do vídeo, ele transcreve e gera um artigo pronto para revisão.

O mesmo vale para Gustavo Dev Doido, o Crazystack Typescript e o Bootcamp do Dev Doido, que reúnem conteúdo técnico em vídeo que poderia render artigos. Com o Skala Blog, a transcrição vira rascunho e o conhecimento sai da gravação para a leitura.

Source video