O que é uma API REST (não é um padrão)

Quem trabalha com desenvolvimento web ouve o termo "API REST" o tempo todo. E é comum ver esse termo sendo usado errado, principalmente chamando o REST de "padrão" ou "protocolo". Neste artigo eu quero explicar o que o REST realmente é, de onde ele surgiu, e por que essa diferença de nomenclatura tem valor técnico.

De onde vem o REST

REST significa Representational State Transfer. O termo foi criado por Roy Fielding, um dos criadores do protocolo HTTP, na sua tese de doutorado de 2000, chamada "Architectural Styles and the Design of Network-based Software Architectures".

Repare no título da tese: ele fala em estilos arquiteturais. Fielding não estava criando uma especificação fechada com regras obrigatórias, como acontece com um protocolo. Ele descreveu um conjunto de princípios que, quando seguidos, resultam em sistemas mais escaláveis, simples e desacoplados entre cliente e servidor.

Padrão, protocolo e estilo arquitetural não são a mesma coisa

Vale separar bem esses três conceitos:

Um protocolo é um conjunto de regras formais para comunicação entre sistemas. O HTTP é um protocolo: ele define exatamente como uma requisição e uma resposta devem ser montadas, com métodos, cabeçalhos, códigos de status.

Um padrão (standard) é uma especificação formalizada, geralmente mantida por uma organização como o W3C ou o IETF, que precisa ser seguida à risca. O SOAP é um bom exemplo, com contrato formal em XML através do WSDL.

Um estilo arquitetural é um conjunto de princípios que orienta como projetar um sistema, sem impor uma única forma de implementação. Há espaço para adaptação.

O REST é, portanto, a terceira coisa. Ele não obriga um formato de mensagem (pode ser JSON, XML, texto puro), não exige uma linguagem específica e não tem nenhum órgão que certifique se uma API "é REST de verdade". O que existe são diretrizes que, quando seguidas, fazem uma API ser chamada de RESTful.

Por isso o correto é dizer que uma API segue o estilo REST, ou que ela é RESTful. Dizer que ela "segue o padrão REST" é um deslize técnico bem comum, mas ainda assim um deslize.

As restrições do estilo REST

Fielding definiu seis restrições que, juntas, formam o REST.

• Cliente-servidor: separação entre quem consome os dados e quem os fornece, para que os dois lados evoluam de forma independente.
• Stateless: cada requisição precisa carregar todas as informações que o servidor precisa para entendê-la. O servidor não guarda o estado da sessão entre requisições.
• Cacheable: as respostas devem indicar se podem ser armazenadas em cache ou não, o que ajuda no desempenho e na escalabilidade.
• Interface uniforme: provavelmente a restrição mais conhecida. Os recursos são identificados por URIs, manipulados por representações (como JSON) e as mensagens se autodescrevem.
• Sistema em camadas: o cliente não precisa saber se está falando direto com o servidor final ou com um intermediário, como um proxy ou um balanceador de carga.
• Código sob demanda: a única restrição opcional. Permite que o servidor envie código executável para rodar no cliente.

Um sistema que respeita essas restrições, principalmente a interface uniforme, é considerado RESTful de verdade.

O papel do HTTP

O REST não exige o uso do HTTP, mas na prática é o protocolo mais usado para implementar APIs RESTful, porque ele já entrega boa parte do que o estilo pede: métodos padronizados, códigos de status, cabeçalhos de cache.

No dia a dia isso vira usar os métodos HTTP com o sentido certo. O GET serve para obter um recurso. O POST serve para criar um recurso novo. O PUT atualiza um recurso por completo, substituindo tudo o que já existe. O PATCH atualiza um recurso parcialmente, alterando só o que for necessário. E o DELETE remove um recurso.

E organizar os recursos em URIs claras, baseadas em substantivos:

GET    /usuarios
GET    /usuarios/42
POST   /usuarios
PUT    /usuarios/42
DELETE /usuarios/42

Somado ao uso correto dos códigos de status (200, 201, 204, 400, 404, 500), isso cria uma API previsível, que é o objetivo da interface uniforme.

O modelo de maturidade de Richardson

Leonard Richardson propôs um jeito prático de medir o quanto uma API é REST de fato, conhecido como Richardson Maturity Model. São quatro níveis, de 0 a 3.

• No NÍVEL 0 existe um único endpoint, geralmente só com POST, funcionando como uma chamada RPC disfarçada de REST.
• No NÍVEL 1 já existem múltiplos recursos com URIs próprias, mas ainda sem uso correto dos métodos HTTP.
• No NÍVEL 2 os verbos HTTP e os códigos de status são usados corretamente.
• No NÍVEL 3 entra o HATEOAS (Hypermedia as the Engine of Application State), em que as respostas trazem links indicando as próximas ações possíveis. Esse é o nível considerado mais fiel ao que Fielding descreveu originalmente.

Vale notar que a maioria das APIs chamadas de "REST" no mercado para no nível 2, sem HATEOAS. Isso não torna essas APIs erradas, mas mostra como o termo REST acabou sendo usado de um jeito mais solto do que a definição original.

Por que isso é importante

Entender que o REST é um estilo arquitetural, e não um padrão fechado, muda como se pensa o design de uma API. Não existe certificação REST nem órgão regulador que valide se uma API está "correta". Há liberdade para adaptar as práticas ao contexto do projeto, desde que os princípios centrais, como statelessness e o uso adequado dos recursos, sejam respeitados. Cobrar "conformidade total com o padrão REST" de uma equipe é, tecnicamente, um erro conceitual. O mais correto é falar em boas práticas RESTful e em nível de maturidade da API.

Conclusão

REST não é protocolo, nem especificação formal, nem padrão certificável. É um estilo arquitetural, um conjunto de princípios propostos por Roy Fielding para guiar o design de sistemas distribuídos escaláveis e desacoplados. O HTTP é o protocolo, e é o principal meio prático de colocar o estilo REST em ação, mas não o único possível.

Saber diferenciar esses conceitos ajuda a projetar APIs mais consistentes e também mostra maturidade técnica em discussões de arquitetura e em processos seletivos.

Referência: FIELDING, Roy Thomas. Architectural Styles and the Design of Network-based Software Architectures. 2000. Tese (Doutorado), University of California, Irvine. (http://ics.uci.edu/~fielding/pubs/dissertation/top.htm).