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

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.

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

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

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.

'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.

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

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.

Eu tenho uma lista de diretrizes em http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html que usamos no prod. As diretrizes são sempre discutíveis ... Eu acho que a consistência às vezes é mais importante do que aperfeiçoar as coisas (se houver).

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.

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

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