Existem diretrizes de convenções de nomenclatura para APIs REST? [fechadas]

212

Ao criar APIs REST, existem diretrizes ou padrões padrão para convenções de nomenclatura na API (por exemplo: componentes do caminho do terminal da URL, parâmetros da string de consulta)? As tampas de camelo são a norma ou sublinhados? outras?

Por exemplo:

api.service.com/helloWorld/userId/x

ou

api.service.com/hello_world/user_id/x

Nota: Esta não é uma questão de design da API RESTful, mas as diretrizes da convenção de nomenclatura a serem usadas para os eventuais componentes do caminho e / ou parâmetros da cadeia de consulta usados.

Qualquer orientação seria apreciada.

jnorris
fonte

Respostas:

150

Eu acho que você deve evitar gorros de camelo. A norma é usar letras minúsculas. Eu também evitaria sublinhados e usaria traços

Portanto, seu URL deve ficar assim (ignorando os problemas de design conforme solicitado :-))

api.service.com/hello-world/user-id/x
LiorH
fonte
187
De acordo com a RFC2616, apenas as partes do esquema e do host da URL não diferenciam maiúsculas de minúsculas. O resto da URL, ou seja, o caminho e a consulta devem ser sensíveis a maiúsculas e minúsculas. w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.2.3
Darrel Miller
10
Daniel, você está certo, obrigado por apontar isso. No entanto, geralmente esperamos que os URLs ignorem os casos, especialmente a parte do nome do recurso. Não faria sentido para UserID & UserId a se comportar de forma diferente (a não ser que um deles retorna 404)
LiorH
18
@LiorH: Por que você acha que "não faz sentido" fazer distinção entre maiúsculas e minúsculas? Muitos outros contextos diferenciam maiúsculas de minúsculas. Existem alguns serviços web (por exemplo, Amazon S3) que fazer valer caso sensibilidade para terminais de URL, e eu acho que é bastante apropriado.
Hank
6
Sistemas de arquivos do servidor @ Dennis Windows são diferencia maiúsculas de minúsculas por padrão, a menos que eu estou muito enganado technet.microsoft.com/en-us/library/cc725747.aspx
samspot
5
@samspot Good one! Eu pensei que o Windows tinha ido direto para maiúsculas e minúsculas quando criaram servidores. WOW, eles ainda estavam empurrando o seu caminho o máximo que podiam, ou seja, "1 MicroSoft Way". ;-)
Dennis
87

A API REST para Dropbox , Twitter , Google Web Services e Facebook usa sublinhados.

jz1108
fonte
24
Um dos efeitos colaterais disso é que as "palavras" sublinhadas são mantidas inteiras, juntas nos índices de pesquisa do Google. Os hifenizados são divididos em palavras separadas.
Dennis
Exemplo: dev.twitter.com/docs/api/1.1
mike kozelsky
11
Enquanto a API do Google Maps usa sublinhados, o Guia de estilo do Google exige Camel Case. A API do Google+ e a API de pesquisa personalizada , entre outras, usam Camel Case.
Benjamin
2
No entanto, eles ainda usam '-' como separador desses URLs: P developers.google.com/custom-search/json-api/v1/reference/cse/… developers.google.com/+/best-practices dev.twitter. por / visão geral / estudos de caso Por outro lado, eles usam camelCase nos parâmetros de consulta.
Mattias
1
Ninguém sabe ...
Piotr Kula
84

Observe atentamente os URIs para obter recursos comuns da Web. Esse é o seu modelo. Pense em árvores de diretório; use nomes simples de arquivos e diretórios semelhantes ao Linux.

HelloWorldnão é realmente uma boa classe de recursos. Não parece ser uma "coisa". Pode ser, mas não é muito parecido com um substantivo. A greetingé uma coisa.

user-idpode ser um substantivo que você está buscando. É duvidoso, no entanto, que o resultado da sua solicitação seja apenas um user_id. É muito mais provável que o resultado da solicitação seja um usuário. Portanto, useré o substantivo que você está buscando

www.example.com/greeting/user/x/

Faz sentido para mim. Concentre-se em fazer com que sua solicitação REST seja um tipo de frase substantiva - um caminho através de uma hierarquia (ou taxonomia ou diretório). Use os substantivos mais simples possíveis, evitando frases substantivas, se possível.

Geralmente, frases substantivas compostas geralmente significam outro passo em sua hierarquia. Então você não tem /hello-world/user/e /hello-universe/user/. Você tem /hello/world/user/e hello/universe/user/. Ou possivelmente /world/hello/user/e/universe/hello/user/ .

O objetivo é fornecer um caminho de navegação entre os recursos.

S.Lott
fonte
4
Minha pergunta é mais sobre a convenção de nomenclatura dos possíveis nomes de caminho e / ou parâmetros de querystring, quaisquer que sejam. Concordo com as recomendações de design, portanto, obrigado, mas com esta pergunta, estou apenas perguntando sobre convenções de nomenclatura.
jnorris
1
Apenas para observar, não há nada que o impeça de usar o REST para recursos não hierárquicos. As convenções de nomenclatura de URI atuais que você usa são irrelevantes, basta usar o que achar bom e fácil de analisar no servidor. O cliente não deve saber nada sobre como gerar seus URIs, pois você precisa enviá-los aos recursos via hipertexto em suas respostas.
aehlke 21/07/2009
30

'UserId' é totalmente a abordagem errada. A abordagem Verbo (Métodos HTTP) e Substantivo é o que Roy Fielding significava para a arquitetura REST . Os substantivos são:

  1. Uma coleção de coisas
  2. Uma coisa

Uma boa convenção de nomenclatura é:

[POST or Create](To the *collection*)
sub.domain.tld/class_name.{media_type} 

[GET or Read](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[PUT or Update](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[DELETE](of *one* thing)
sub.domain.tld/class_name/id_value.{media_type}

[GET or Search](of a *collection*, FRIENDLY URL)
sub.domain.tld/class_name.{media_type}/{var}/{value}/{more-var-value-pairs}

[GET or Search](of a *collection*, Normal URL)
sub.domain.tld/class_name.{media_type}?var=value&more-var-value-pairs

Onde {media_type} é um dos seguintes: json, xml, rss, pdf, png e até html.

É possível distinguir a coleção adicionando um 's' no final, como:

'users.json' *collection of things*
'user/id_value.json' *single thing*

Mas isso significa que você deve acompanhar onde colocou os 's' e onde não colocou. Além disso, metade do planeta (asiáticos para iniciantes) fala idiomas sem plurais explícitos, portanto a URL é menos amigável para eles.

Dennis
fonte
O que se entende por {var}? Se eu procurar um usuário pelo nome, por exemplo ... / user / username / tomsawyer?
Hans-Peter Störr 30/10/12
1
Se você tivesse três variáveis ​​(var) s nomeadas x, y, z, sua URL se pareceria com: sub.domínio.tld / x / value_of_x / y / value_of_y / z / value_of_z
Dennis
@hstoerr Apenas para ter certeza de que eu estava claro, a maioria das linguagens de script usa algum tipo de 'substituição de variável entre colchetes'. Então {var} significa que alguma variável (seu nome) reside lá e, portanto, o seguinte {value} é onde o valor do {var} antes dela. Exemplo: sub.domain.tld / script / {var} / {value} .json [www.yelp.com/food_reviews/review_averages_higher_than/4.json] estaria tentando obter os resultados do json do yelp.com para obter resultados de alimentos um maior valor de 4.
Dennis
Esta é a melhor resposta na minha opinião e parabéns por pensar internacionalmente.
beiller
14

Não. O REST não tem nada a ver com convenções de nomenclatura de URI. Se você incluir essas convenções como parte de sua API, fora de banda, em vez de apenas via hipertexto, sua API não será RESTful.

Para mais informações, consulte http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

aehlke
fonte
44
Descanse um pouco ... ainda é bom ter URLs com boa aparência.
HDave
1
Concordo com o @HDave, é muito do espírito do REST ter URLs que sejam facilmente compreendidos. Você está trabalhando com URLs, por que não gostaria que eles fossem tão facilmente compreendidos quanto os nomes de variáveis ​​e parâmetros em seu código?
Mahemoff
4
@ Mahemoff desculpe, este sou eu sendo super pedante. Mas a aparência de seus URLs não tem nada a ver com o REST. Isso não significa que eles não são uma coisa boa de ter, são apenas ortogonais ao que o REST descreve. É enganoso dizer que o REST trata da estruturação de URLs dessa maneira, pois leva as pessoas a descreverem as APIs de RPC como REST apenas porque possuem URLs legíveis / estruturados.
precisa saber é
5
Em resumo, os URLs com boa aparência são ótimos e todos deveriam tê-los. Porém, não tem nada a ver com o REST.
precisa saber é
1
@aehlke obrigado por esclarecer isso. O descanso não é sobre estruturas de URL. Não entendo por que é tão difícil para as pessoas entenderem.
user1431072
9

Os nomes de domínio não diferenciam maiúsculas de minúsculas, mas o resto do URI certamente pode ser. É um grande erro supor que os URIs não diferenciam maiúsculas de minúsculas.


fonte
2

Não acho que o caso camel seja o problema nesse exemplo, mas imagino que uma convenção de nomenclatura mais RESTful para o exemplo acima seria:

api.service.com/helloWorld/userId/x

em vez de tornar userId um parâmetro de consulta (o que é perfeitamente legal), meu exemplo denota esse recurso, IMO, de uma maneira mais RESTful.

Gandalf
fonte
Isso não é uma questão de design da API RESTful, mas das diretrizes da convenção de nomenclatura a serem usadas para os eventuais componentes do caminho e / ou parâmetros da string de consulta usados. No seu exemplo, os componentes do caminho devem estar em tampas de camelo como você usou ou sublinhados?
jnorris
Bem, como no REST seus URLs são suas interfaces, é uma questão de API. Embora eu não ache que haja diretrizes específicas para o seu exemplo, eu aceitaria pessoalmente o caso camel.
Gandalf
Você não deve usar parâmetros de consulta para recursos que deseja que sejam armazenados em cache em qualquer nível da pilha HTTP.
aehlke 21/07/2009
@aehlke O oposto exato também é verdadeiro. Se você NÃO deseja que os parâmetros de consulta sejam armazenados em cache, use o estilo GET para os parâmetros, ~ OU ~ faça DARN SURE para modificar / inserir cabeçalhos anti-cache para qualquer coisa que você não deseja que seja armazenada em cache. Além disso, existem três cabeçalhos que são um hash do objeto / página retornado; use isso para indicar alterações das coisas que você deseja que sejam armazenadas em cache, mas atualizadas quando houver edições.
Dennis
@aehlke Descobri o cache e estou adicionando. Lembro-me de uma apresentação do CodeCamp em que um dos aceleradores fazia todos esses cabeçalhos e, em seguida, alterava o nome do arquivo e todas as referências a ele quando o conteúdo foi alterado para fazer com que os borwsers e proxies usassem uma versão mais recente após um longo tempo de cache. conjunto. Aqui estão todos os detalhes sangrentos: developers.google.com/speed/docs/best-practices/caching
Dennis
2

Se você autenticar seus clientes com o Oauth2, acho que precisará de sublinhado para pelo menos dois dos seus nomes de parâmetro:

  • ID do Cliente
  • client_secret

Eu usei o camelCase na minha API REST (ainda não publicada). Enquanto escrevia a documentação da API, estive pensando em mudar tudo para snake_case, para não precisar explicar por que os parâmetros de Oauth são snake_case, enquanto outros não.

Veja: https://tools.ietf.org/html/rfc6749

Michael
fonte
0

Eu diria que é preferível usar o mínimo de caracteres especiais possível nos URLs REST. Um dos benefícios do REST é que ele facilita a leitura da "interface" de um serviço. O caso Camel ou Pascal provavelmente é bom para os nomes de recursos (usuários ou usuários). Eu não acho que exista realmente algum padrão rígido em relação ao REST.

Além disso, acho que Gandalf está certo, geralmente é mais limpo no REST não usar parâmetros de string de consulta, mas criar caminhos que definem com quais recursos você deseja lidar.

http://api.example.com/HelloWorld/Users/12345/Order/3/etc

Andy White
fonte