APIs: Pluralização, Hierarquias e Relações

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 por 100 dessa colecção. Não o elemento 100 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 que POST 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 aos users a API deverá implementar um método GET 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étodo GET 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.