📌 17 de Agosto, 2015
APIs: Pluralização, Hierarquias e Relações
Informática · Programação
Neste artigo continuo a falar sobre a teoria e a prática de desenvolvimento de boas APIs. Caso ainda não tenha lido o artigo anterior, APIs: RESTFul, Nomes de Recursos e Acções deverá fazê-lo antes de prosseguir.
Pluralização
Falemos agora um antigo debate: Os nomes dos recursos deverão ser apresentados no singular ou no plural? Existem diversas discussões sobre este assunto, online, no entanto é genericamente aceite que estes deverão estar no plural porque:
- Ao obter uma lista de utilizadores com
GET http://api.dev/users
esperamos receber vários elementos já que o recurso/users
é uma colecção e não faria sentido este chamar-se/user
; - Ao obter um utilizador específico
GET http://api.dev/users/100
a mesma lógica anterior é seguida,/users
é uma colecção e nós queremos o elemento identificado por100
dessa colecção. Não o elemento100
de outro elemento; - Existem alguns recursos que não são colecções, exemplo
GET http://api.dev/version
; - Ao criar uma nova entidade,
POST http://api.dev/users
faz mais sentido do quePOST http://api.dev/user
já o que pretendemos é criar um elemento novo numa colecção existente; - Quando temos uma hierarquia como
GET http://api.dev/users/1/orders/10
a não pluralização poderá levar também a colisão semântica.
A reter: Qualquer nome deverá ser pluralizado à excepção de quando se trate de um singleton, um recurso único onde não é aplicável a noção de colecção.
Hierarquias e Relações
Numa API RESTFul o importante é perceber que as hierarquias e as relações dos dados nos URIs não devem ser definidas a partir do modelo da base de dados mas sim a partir das necessidades de consumo da API. Estas necessidades podem ser percebidas através da análise dos requisitos das aplicações que a vão utilizar.
Caso uma aplicação:
- Mostre sempre elementos da entidade
orders
associados aosusers
a API deverá implementar um métodoGET http://api.dev/users/5/orders
; - Tenha uma área dedicada a listar todas as
orders
, independente do utilizador associado, deverá então ser implementado um métodoGET http://api.dev/orders
.
A reter: As APIs deverão ser desenhadas em torno das necessidades das aplicações que as consomem. Em caso de dúvida até podem ser implementados endpoints diferentes que irão obter a mesma informação, como acontecia se implementássemos as duas opções em cima.
No próximo artigo irei falar sobre Devolução de Dados e Gestão de Erros.