Convenção REST URI - Nome singular ou plural do recurso ao criá-lo

Eu sou novo no REST e observei que em alguns serviços RESTful eles usam URI de recursos diferentes para atualizar / obter / excluir e Criar. Tal como

• Criar - usando / recursos com o método POST (observe o plural) em alguns lugares usando / resource (singular)
• Atualização - usando / resource / 123 com o método PUT
• Obter - Usando / resource / 123 com o método GET

Estou um pouco confuso sobre esta convenção de nomes de URI. O que devemos usar no plural ou no singular para criação de recursos? Quais devem ser os critérios ao decidir isso?

A premissa de usar /resourcesé que ele representa "todos" os recursos. Se você fizer um GET /resources, provavelmente retornará a coleção inteira. Ao postar em /resources, você está adicionando à coleção.

No entanto, os recursos individuais estão disponíveis em / resource. Se você fizer um GET /resource, provavelmente cometerá um erro, pois essa solicitação não faz nenhum sentido, enquanto /resource/123faz todo o sentido.

Usando /resourcevez de /resourcesé semelhante à forma como você faria isso se estivesse a trabalhar com, digamos, um sistema de arquivos e uma coleção de arquivos e /resourceé o "diretório" com o indivíduo 123, 456arquivos nele.

De nenhuma maneira é certo ou errado, escolha o que você mais gosta.

Para mim, é melhor ter um esquema que você possa mapear diretamente para o código (fácil de automatizar), principalmente porque o código é o que será nas duas extremidades.

GET  /orders          <---> orders 
POST /orders          <---> orders.push(data)
GET  /orders/1        <---> orders[1]
PUT  /orders/1        <---> orders[1] = data
GET  /orders/1/lines  <---> orders[1].lines
POST /orders/1/lines  <---> orders[1].lines.push(data) 

Também não vejo sentido em fazer isso e acho que não é o melhor design de URI. Como usuário de um serviço RESTful, eu esperaria que o recurso da lista tivesse o mesmo nome, independentemente de acessar a lista ou o recurso específico 'na' lista. Você deve usar os mesmos identificadores, independentemente de querer usar o recurso de lista ou um recurso específico.

Plural

• Simples - todos os URLs começam com o mesmo prefixo
• Lógico - orders/obtém uma lista de pedidos de índice.
• Padrão - O padrão mais amplamente adotado, seguido pela esmagadora maioria das APIs públicas e privadas.

Por exemplo:

GET /resources - retorna uma lista de itens de recursos

POST /resources - cria um ou muitos itens de recursos

PUT /resources - atualiza um ou muitos itens de recursos

PATCH /resources - atualiza parcialmente um ou muitos itens de recursos

DELETE /resources - exclui todos os itens de recursos

E para itens de recurso único:

GET /resources/:id- retorna um item de recurso específico com base no :idparâmetro

POST /resources/:id - cria um item de recurso com o ID especificado (requer validação)

PUT /resources/:id - atualiza um item de recurso específico

PATCH /resources/:id - atualiza parcialmente um item de recurso específico

DELETE /resources/:id - exclui um item de recurso específico

Para os defensores do singular, pense dessa maneira: você pediria a alguém ordere esperaria uma coisa ou uma lista de coisas? Então, por que você esperaria que um serviço retornasse uma lista de itens ao digitar /order?

Singular

Conveniência As coisas podem ter nomes irregulares no plural. Às vezes eles não têm um. Mas nomes singulares estão sempre lá.

por exemplo, CustomerAddress sobre CustomerAddresses

Considere este recurso relacionado.

Isso /order/12/orderdetail/12é mais legível e lógico do que /orders/12/orderdetails/4.

Tabelas de banco de dados

Um recurso representa uma entidade como uma tabela de banco de dados. Deve ter um nome singular lógico. Aqui está a resposta sobre os nomes das tabelas.

Mapeamento de Classes

As aulas são sempre singulares. As ferramentas ORM geram tabelas com os mesmos nomes dos nomes de classe. À medida que mais e mais ferramentas estão sendo usadas, nomes singulares estão se tornando um padrão.

Leia mais sobre o dilema de um desenvolvedor de API REST

Enquanto a prática mais prevalente são as APIs RESTful onde plurais são usados /api/resources/123, por exemplo , há um caso especial em que considero o uso de um nome singular mais apropriado / expressivo do que nomes plurais. É o caso dos relacionamentos um-para-um. Especificamente, se o item de destino for um objeto de valor (no paradigma de design controlado por domínio).

Vamos supor que todo recurso tenha um um para um, accessLogque pode ser modelado como um objeto de valor, ou seja, não uma entidade, portanto, sem ID. Pode ser expresso como /api/resources/123/accessLog. Os verbos usuais (POST, PUT, DELETE, GET) expressariam adequadamente a intenção e também o fato de que o relacionamento é realmente um para um.

Por que não seguir a tendência predominante dos nomes de tabelas de banco de dados, onde geralmente é aceito um formulário singular? Estive lá, fiz isso - vamos reutilizar.

Dilema de nomeação de tabela: nomes singulares vs. plurais

Estou surpreso ao ver que tantas pessoas pulariam no substantivo plural bandwagon. Ao implementar conversões no singular para o plural, você cuida de substantivos no plural irregulares? Você gosta de dor?

Consulte http://web2.uvcs.uvic.ca/elc/studyzone/330/grammar/irrplu.htm

Existem muitos tipos de plural irregular, mas estes são os mais comuns:

Tipo substantivo Formando o plural Exemplo

Ends with -fe   Change f to v then Add -s   
    knife   knives 
    life   lives 
    wife   wives
Ends with -f    Change f to v then Add -es  
    half   halves 
    wolf   wolves
    loaf   loaves
Ends with -o    Add -es 
    potato   potatoes
    tomato   tomatoes
    volcano   volcanoes
Ends with -us   Change -us to -i    
    cactus   cacti
    nucleus   nuclei
    focus   foci
Ends with -is   Change -is to -es   
    analysis   analyses
    crisis   crises
    thesis   theses
Ends with -on   Change -on to -a    
    phenomenon   phenomena
    criterion   criteria
ALL KINDS   Change the vowel or Change the word or Add a different ending   
     man   men
     foot   feet
     child   children
     person   people
     tooth   teeth
     mouse   mice
 Unchanging Singular and plural are the same    
     sheep deer fish (sometimes)

Da perspectiva do consumidor da API, os pontos de extremidade devem ser previsíveis para que

Idealmente...

1. GET /resources deve retornar uma lista de recursos.
2. GET /resource deve retornar um código de status de 400 níveis.
3. GET /resources/id/{resourceId} deve retornar uma coleção com um recurso.
4. GET /resource/id/{resourceId} deve retornar um objeto de recurso.
5. POST /resources o lote deve criar recursos.
6. POST /resource deve criar um recurso.
7. PUT /resource deve atualizar um objeto de recurso.
8. PATCH /resource deve atualizar um recurso postando apenas os atributos alterados.
9. PATCH /resources Os recursos de atualização em lote devem postar apenas os atributos alterados.
10. DELETE /resourcesdeve excluir todos os recursos; brincando: código de status 400
11. DELETE /resource/id/{resourceId}

Essa abordagem é a mais flexível e rica em recursos, mas também a que consome mais tempo. Portanto, se você estiver com pressa (o que é sempre o caso do desenvolvimento de software), apenas nomeie seu endpoint resourceou a forma plural resources. Eu prefiro a forma singular, pois oferece a opção de examinar e avaliar programaticamente, pois nem todas as formas plurais terminam em 's'.

Dito tudo isso, por qualquer motivo que o desenvolvedor da prática mais comumente escolhido tenha escolhido é usar a forma plural. Esta é finalmente a rota que eu escolhi e se você olhar as APIs populares como githubetwitter , é isso que elas fazem.

Alguns critérios para decidir podem ser:

1. Quais são as minhas restrições de tempo?
2. Quais operações permitirei que meus consumidores façam?
3. Como é a carga útil da solicitação e do resultado?
4. Quero poder usar a reflexão e analisar o URI no meu código?

Então a escolha é sua. Seja o que for que seja consistente.

Meus dois centavos: métodos que passam seu tempo mudando do plural para o singular ou vice-versa são um desperdício de ciclos de CPU. Eu posso ser da velha escola, mas na minha época as coisas eram chamadas da mesma forma. Como procuro métodos relacionados a pessoas? Nenhuma expressão regular cobre pessoas e pessoas sem efeitos colaterais indesejáveis.

Os plurais em inglês podem ser muito arbitrários e sobrecarregam o código desnecessariamente. Atenha-se a uma convenção de nomenclatura. As linguagens de computador deveriam ter clareza matemática, não imitar a linguagem natural.

Eu prefiro usar a forma singular para simplicidade e consistência.

Por exemplo, considerando o seguinte URL:

/ cliente / 1

Tratarei o cliente como uma coleção de clientes, mas por simplicidade, a parte da coleção é removida.

Outro exemplo:

/ equipamento / 1

Nesse caso, equipamentos não é a forma plural correta. Portanto, tratá-lo como uma coleção de equipamentos e remover a coleção por simplicidade torna-o consistente com o caso do cliente.

Um ID em uma rota deve ser exibido da mesma forma que um índice para uma lista e a nomeação deve prosseguir de acordo.

numbers = [1, 2, 3]

numbers            GET /numbers
numbers[1]         GET /numbers/1
numbers.push(4)    POST /numbers
numbers[1] = 23    UPDATE /numbers/1

Mas alguns recursos não usam IDs em suas rotas porque há apenas um ou um usuário nunca tem acesso a mais de um, portanto, essas não são listas:

GET /dashboard
DELETE /session
POST /login
GET /users/{:id}/profile
UPDATE /users/{:id}/profile

Nas convenções de nomenclatura, geralmente é seguro dizer "apenas escolha uma e cumpra-a", o que faz sentido.

No entanto, depois de ter que explicar o REST para muitas pessoas, representar os pontos de extremidade como caminhos em um sistema de arquivos é a maneira mais expressiva de fazê-lo.
É sem estado (os arquivos existem ou não existem), hierárquico, simples e familiar - você já sabe como acessar arquivos estáticos, localmente ou via http.

E, nesse contexto, as regras lingüísticas podem levá-lo até o seguinte:

Um diretório pode conter vários arquivos e / ou subdiretórios e, portanto, seu nome deve estar na forma plural.

E eu gosto disso.
Embora, por outro lado - seja seu diretório, você pode chamá-lo de "um recurso ou vários recursos", se é isso que você deseja. Isso não é realmente o importante.

O importante é que, se você colocar um arquivo chamado "123" em um diretório chamado "resourceS" (resultando em /resourceS/123), não poderá esperar que ele seja acessível via/resource/123 .

Não tente torná-lo mais inteligente do que deveria ser - mudar de plural para singluar, dependendo da quantidade de recursos que você está acessando no momento, pode ser esteticamente agradável para alguns, mas não é eficaz e não faz sentido em um hierárquico sistema .

Nota: Tecnicamente, você pode criar "links simbólicos", para que /resources/123também possam ser acessados ​​via /resource/123, mas o primeiro ainda precisa existir!

Dê uma olhada no Google 's Guia de Design do API: Nomes de Recursos para outra tomada sobre os recursos de nomeação.

Em resumo:

• As coleções são nomeadas com plurais.
• Recursos individuais são nomeados com uma sequência.

|--------------------------+---------------+-------------------+---------------+--------------|
| API Service Name         | Collection ID | Resource ID       | Collection ID | Resource ID  |
|--------------------------+---------------+-------------------+---------------+--------------|
| //mail.googleapis.com    | /users        | /[email protected] | /settings     | /customFrom  |
| //storage.googleapis.com | /buckets      | /bucket-id        | /objects      | /object-id   |
|--------------------------+---------------+-------------------+---------------+--------------|

Vale a pena ler se você está pensando sobre esse assunto.

Usar o plural para todos os métodos é mais prático, pelo menos em um aspecto: se você estiver desenvolvendo e testando uma API de recurso usando o Postman (ou ferramenta similar), não precisará editar o URI ao alternar de GET para PUT para POST etc. .

Ambas as representações são úteis. Eu tinha usado o singular por conveniência há algum tempo, a inflexão pode ser difícil. Minha experiência no desenvolvimento de APIs REST estritamente singulares, os desenvolvedores que consomem o endpoint não têm certeza de qual seja a forma do resultado. Agora, prefiro usar o termo que melhor descreve a forma da resposta.

Se todos os seus recursos forem de nível superior, você poderá obter representações singulares. Evitar a inflexão é uma grande vitória.

Se você está fazendo algum tipo de link direto para representar consultas sobre relações, os desenvolvedores que escrevem na sua API podem ser auxiliados por uma convenção mais rígida.

Minha convenção é que cada nível de profundidade em um URI está descrevendo uma interação com o recurso pai, e o URI completo deve descrever implicitamente o que está sendo recuperado.

Suponha que tenhamos o seguinte modelo.

interface User {
    <string>id;
    <Friend[]>friends;
    <Manager>user;
}

interface Friend {
    <string>id;
    <User>user;
    ...<<friendship specific props>>
}

Se eu precisasse fornecer um recurso que permita que um cliente obtenha o gerente de um amigo em particular de um usuário em particular, pode parecer algo como:

GET /users/{id}/friends/{friendId}/manager

A seguir, apresentamos mais alguns exemplos:

• GET /users - liste os recursos do usuário na coleção de usuários globais
• POST /users - crie um novo usuário na coleção de usuários globais
• GET /users/{id} - recuperar um usuário específico da coleção de usuários globais
• GET /users/{id}/manager - obtenha o gerente de um usuário específico
• GET /users/{id}/friends - obtenha a lista de amigos de um usuário
• GET /users/{id}/friends/{friendId} - obtenha um amigo específico de um usuário
• LINK /users/{id}/friends - adicione uma associação de amigos a este usuário
• UNLINK /users/{id}/friends - remover uma associação de amigos deste usuário

Observe como cada nível é mapeado para um pai que pode agir. Usar pais diferentes para o mesmo objeto é contra-intuitivo. A recuperação de um recurso em GET /resource/123não deixa indicação de que a criação de um novo recurso deve ser feita emPOST /resources

Eu sei que a maioria das pessoas está entre decidir entre usar o plural ou o singular. O problema que não foi abordado aqui é que o cliente precisará saber qual você está usando e é sempre provável que cometa um erro. É daí que vem minha sugestão.

E os dois? E com isso, quero dizer usar singular para toda a API e criar rotas para encaminhar solicitações feitas no plural para o singular. Por exemplo:

GET  /resources     =     GET  /resource
GET  /resources/1   =     GET  /resource/1
POST /resources/1   =     POST /resource/1
...

Você entendeu a foto. Ninguém está errado, com um esforço mínimo, e o cliente sempre acertará.

Não gosto de ver a {id}parte dos URLs se sobrepor aos sub-recursos, pois, idteoricamente, isso poderia ser qualquer coisa e haveria ambiguidade. Está misturando diferentes conceitos (identificadores e nomes de sub-recursos).

Problemas semelhantes são freqüentemente vistas em enumconstantes ou pasta estruturas, onde diferentes conceitos são misturados (por exemplo, quando você tem pastas Tigers, Lionse Cheetahs, em seguida, também uma pasta chamada Animalsno mesmo nível - isso não faz sentido como um é um subconjunto do de outros).

Em geral, acho que a última parte nomeada de um endpoint deve ser singular se lida com uma única entidade de cada vez e plural se lida com uma lista de entidades.

Portanto, terminais que lidam com um único usuário:

GET  /user             -> Not allowed, 400
GET  /user/{id}        -> Returns user with given id
POST /user             -> Creates a new user
PUT  /user/{id}        -> Updates user with given id
DELETE /user/{id}      -> Deletes user with given id

Depois, há um recurso separado para fazer consultas aos usuários, que geralmente retornam uma lista:

GET /users             -> Lists all users, optionally filtered by way of parameters
GET /users/new?since=x -> Gets all users that are new since a specific time
GET /users/top?max=x   -> Gets top X active users

E aqui estão alguns exemplos de um sub-recurso que lida com um usuário específico:

GET /user/{id}/friends -> Returns a list of friends of given user

Faça um amigo (link muitos para muitos):

PUT /user/{id}/friend/{id}     -> Befriends two users
DELETE /user/{id}/friend/{id}  -> Unfriends two users
GET /user/{id}/friend/{id}     -> Gets status of friendship between two users

Nunca há ambiguidade, e a nomeação plural ou singular do recurso é uma dica para o usuário o que ele pode esperar (lista ou objeto). Não há restrições sobre ids, teoricamente tornando possível ter um usuário com o ID newsem sobrepor-se a um nome de sub-recurso (potencial futuro).

Use o Singular e aproveite a convenção em inglês vista em, por exemplo, "Business Directory".

Muitas coisas são lidas desta maneira: "estante de livros", "matilha de cães", "galeria de arte", "festival de cinema", "estacionamento de carros" etc.

Isso corresponde convenientemente ao caminho da URL da esquerda para a direita. Tipo de item à esquerda. Defina o tipo à direita.

Será que GET /usersrealmente sempre buscar um conjunto de usuários? Normalmente não. Ele busca um conjunto de stubs contendo uma chave e talvez um nome de usuário. Portanto, não é realmente /usersassim mesmo. É um índice de usuários, ou um "índice de usuário", se você preferir. Por que não chamar assim? É um /user/index. Como nomeamos o tipo de conjunto, podemos ter vários tipos mostrando diferentes projeções de um usuário sem recorrer a parâmetros de consulta, por exemplo, user/phone-listou /user/mailing-list.

E o Usuário 300? Ainda está /user/300.

GET /user/index
GET /user/{id}

POST /user
PUT /user/{id}

DELETE /user/{id}

No fechamento, o HTTP pode ter apenas uma única resposta para uma única solicitação. Um caminho está sempre se referindo a algo singular.

Para mim, os plurais manipulam a coleção , enquanto os singulares manipulam o item dentro dessa coleção.

A coleção permite os métodos GET / POST / DELETE

O item permite os métodos GET / PUT / DELETE

Por exemplo

O POST em / alunos adicionará um novo aluno à escola.

DELETE ativado / alunos removerá todos os alunos da escola.

DELETE em / student / 123 removerá o aluno 123 da escola.

Pode parecer sem importância, mas alguns engenheiros às vezes esquecem o id. Se a rota sempre foi plural e executou um DELETE, você pode acidentalmente limpar seus dados. Enquanto a falta do ID no singular retornará uma rota 404 não encontrada.

Para expandir ainda mais o exemplo, se a API deveria expor várias escolas, algo como

DELETE em / school / abc / students removerá todos os alunos da escola abc.

Escolher a palavra certa às vezes é um desafio por si só, mas eu gosto de manter a pluralidade da coleção. Por exemplo, cart_itemsou cart/itemsparece certo. Ao contrário cart, a exclusão exclui o objeto do carrinho e não os itens do carrinho;).

E se:

/resource/ (não /resource )

/resource/ significa que uma pasta contém algo chamado "recurso", é uma pasta "recurso".

E também acho que a convenção de nomenclatura das tabelas de banco de dados é a mesma, por exemplo, uma tabela chamada 'user' é uma "tabela de usuário", contém algo chamado "usuário".

Prefiro usar o plural ( /resources) e o singular ( /resource/{id}) porque acho que separa mais claramente a lógica entre trabalhar na coleção de recursos e trabalhar em um único recurso.

Como um efeito colateral importante disso, também pode ajudar a impedir que alguém use a API incorretamente. Por exemplo, considere o caso em que um usuário tenta obter um recurso incorretamente, especificando o ID como um parâmetro como este:

GET /resources?Id=123

Nesse caso, onde usamos a versão plural, o servidor provavelmente ignorará o parâmetro Id e retornará a lista de todos os recursos. Se o usuário não for cuidadoso, ele pensará que a chamada foi bem-sucedida e usará o primeiro recurso da lista.

Por outro lado, ao usar a forma singular:

GET /resource?Id=123

o servidor provavelmente retornará um erro porque o ID não está especificado da maneira correta e o usuário terá que perceber que algo está errado.