Muitas APIs organizam as operações em torno das coisas do negócio, como pedidos, pagamentos e clientes. Reconhecer essa organização ajuda a entender a intenção de uma chamada e a separar o endereço, o método e o resultado.
Recursos e métodos
O REST é um estilo de arquitetura para a comunicação entre sistemas. Nas APIs HTTP organizadas por recursos, a URL identifica o recurso, como uma cobrança ou um pedido, e o método expressa a operação pedida sobre ele. No gateway de pagamento, as chamadas ficam assim:
POST /v1/pagamentos: cria uma cobrança;GET /v1/pagamentos/PAG-0001: consulta a cobrança PAG-0001;GET /v1/pagamentos?pedido_id=PED-0001: lista as cobranças de um pedido.
O endereço nomeia a coisa, e o método diz o que fazer com ela. Por isso, os caminhos de uma API REST costumam ter substantivos, como pagamentos e pedidos, e não verbos.
O que o estilo exige
O estilo REST vai além dos recursos e dos métodos. Entre as características definidas para o estilo estão estas:
- a interface uniforme, com as mesmas regras de acesso para todos os recursos;
- a comunicação sem estado, em que cada requisição traz tudo o que o serviço precisa para atendê-la;
- as regras de cache, que indicam quais respostas podem ser reaproveitadas.
No mercado, APIs com graus diferentes de adesão a essas características são chamadas de REST. A presença de substantivos na URL não comprova todas elas, e o atendimento de uma falha não depende de decidir se a API segue o estilo por completo.
Formato e resultado
O JSON é o formato mais comum nas APIs REST, mas o estilo não exige o JSON. Uma API pode oferecer XML ou outro formato e continuar organizada por recursos. O status HTTP informa o atendimento da requisição, e o corpo ainda pode trazer a aprovação, a recusa ou a pendência do negócio.
Os sinais em uma URL
Alguns contratos misturam recursos e ações. Um caminho como /v1/pagamentos/PAG-0001/estorno representa uma ação sobre a cobrança, e um caminho como /api/ConsultarPreco nomeia uma operação, e não um recurso. Esses nomes orientam a pesquisa na documentação, mas não identificam sozinhos o estilo da API.
A palavra api na URL e uma resposta em JSON são sinais genéricos de uma interface programável. O método, a URL, os cabeçalhos, a mensagem e a documentação, juntos, descrevem a chamada.
No suporte
Para reconstruir uma operação, convém ler o recurso no caminho e a intenção no método e depois confirmar o contrato daquele endereço. A investigação de um campo recusado, de uma credencial inválida ou de um pagamento pendente não depende de classificar a API como REST pura.
Para guardar
- Nas APIs REST, a URL identifica o recurso, e o método expressa a operação.
- O estilo REST também envolve interface uniforme, comunicação sem estado e regras de cache.
- O REST não exige JSON, e a URL sozinha não identifica o estilo.
- O contrato e a resposta completa orientam a interpretação da chamada.
Uma URL contém /api/ConsultarPreco e devolve um JSON. Isso comprova que a API é REST?
Não. O caminho nomeia uma operação, e esses sinais também aparecem em interfaces organizadas por operações. O método, o comportamento e a documentação descrevem a API atendida.
As chamadas GET /v1/pagamentos/PAG-0001 e POST /v1/pagamentos têm a mesma finalidade?
Não. O GET consulta a cobrança PAG-0001, e o POST cria uma cobrança nova. O método faz parte da operação, e o caminho sozinho não determina a intenção.