É razoável que os recursos REST sejam singulares e plurais?

10

Fiquei me perguntando se, em vez de um layout mais tradicional como este:

api/Products
GET // gets product(s) by id
PUT // updates product(s) by id
DELETE // deletes (product(s) by id
POST // creates product(s)

Seria mais útil ter um singular e um plural, por exemplo:

api/Product
GET // gets a product by id
PUT // updates a product by id
DELETE // deletes a product by id
POST // creates a product

api/Products
GET // gets a collection of products by id
PUT // updates a collection of products by id
DELETE // deletes a collection of products (not the products themselves)
POST // creates a collection of products based on filter parameters passed

Portanto, para criar uma coleção de produtos, você pode:

POST api/Products {data: filters} // returns api/Products/<id>

E então, para referenciá-lo, você pode fazer:

GET api/Products/<id> // returns array of products

Na minha opinião, a principal vantagem de fazer as coisas dessa maneira é permitir o armazenamento em cache fácil de coleções de produtos. Pode-se, por exemplo, colocar uma vida útil de uma hora em coleções de produtos, reduzindo drasticamente as chamadas em um servidor. Claro, atualmente só vejo o lado bom de fazer as coisas dessa maneira, qual é a desvantagem?

rest Eva
fonte

Respostas:

6

Frequentemente, quando uma coleção é a maneira mais útil de interagir com sua API, pode ser mais simples pensar em uma única como uma coleção com apenas um membro. Então, se mais tarde você quiser expor uma API para interagir com solteiros, ela apenas precisará converter o single passado em uma coleção com esse membro e usar a implementação idêntica da outra API.

Eu acho que o que estou dizendo aqui é: se você deseja que as coleções sejam um mecanismo de interação, comece com a API somente de coleta e, após a conclusão do sistema, a outra API é um simples acessório auxiliar na camada de interface, você pode adicionar se você acha isso particularmente útil. No entanto, você pode achar que sua utilidade é mínima o suficiente para aplicar o YAGNI e apenas use a interface de coleções para as poucas instâncias de singles que você deseja.

Jimmy Hoffa
fonte
Embora eu concorde com sua opinião, assumindo que usamos o exemplo acima, considerando que a API / produtos POST seria usada para passar parâmetros de filtro de coleta e não dados para a criação de novos produtos, o que seria uma maneira razoável de criar um novo produto sem API / Produto?
Eva
@Evan Por que não é possível postar na API / Produtos inserir vários (ou um conjunto de um) Produtos? Isso parece o mais lógico para mim. Talvez poste Products / Filter para criar filtros ou obtenha se é uma tarefa de recuperação e não de criação.
Jimmy Hoffa
Obrigado pela elaboração, Jimmy. O motivo pelo qual não vi dessa maneira foi que eu estava considerando, no exemplo acima, a coleção como um recurso identificado por si só. Em um back-end, api / Product pode ser "Product" e api / Products, portanto "ProductCollection". No entanto, após algumas considerações, acho que talvez seja melhor resumir que tudo que está longe da API, como na sua sugestão ... agora para a verdadeira questão, você se afastou daquela parada de caminhões a caminho da Tailândia ou saiu na bagageira de um carro?
Eva
@Evan, vou lhe dar duas dicas: gaivotas.
Jimmy Hoffa
1

A desvantagem é que o programa de chamada também precisa pluralizar o nome do recurso, o que pode ser complicado para os idiomas do cliente que não possuem mecanismos de pluralização embutidos. Se você deixar singular, é mais fácil para o chamador automatizar a geração de código para sua biblioteca cliente.

Se você quiser atenuar isso, poderá gerar os SDKs para seu serviço REST. Ou você pode apenas opinar e lidar com a reclamação :)

Chris McCall
fonte