Y a-t-il des règles de nommage pour les API REST? [fermé]
lors de la création D'API REST, y a-t-il des lignes directrices ou des normes de fait pour les conventions de nommage dans L'API (par exemple: composants de chemin D'URL, paramètres de interrogation)? Est-ce que les casquettes de chameau sont la norme, ou les underscores? les autres?
par exemple:
api.service.com/helloWorld/userId/x
ou
api.service.com/hello_world/user_id/x
Note: Il ne s'agit pas D'une question de conception de L'API RESTful, mais plutôt des directives de la convention de nommage à utiliser pour les composants du chemin d'accès et / ou paramètres de la chaîne de requête utilisés.
toute ligne directrice serait appréciée.
10 réponses
je pense que tu devrais éviter les casquettes de chameau. La norme est d'utiliser des lettres minuscules. J'éviterais aussi les soulignements et j'utiliserais plutôt des tirets
donc votre URL devrait ressembler à ceci (ignorant les problèmes de design comme vous l'avez demandé : -))
api.service.com/hello-world/user-id/x
L'API REST pour Dropbox , Twitter , Google Web Services et Facebook toutes les utilisations souligne.
regardez attentivement URI pour les ressources Web ordinaires. Ceux-ci sont à votre modèle. Pensez aux arborescences des répertoires; utilisez des noms de fichiers et de répertoires semblables à ceux de Linux.
HelloWorld n'est pas vraiment une bonne catégorie de ressources. Il ne semble pas être une "chose". Il pourrait être, mais il n'est pas très nom-comme. Un greeting est une chose.
user-id est peut-être un nom que vous cherchez. Il est douteux, cependant, que le résultat de votre demande n'est qu'un user_id. Il est beaucoup plus probable que le résultat de la demande d'un Utilisateur. Par conséquent, user est le nom que vous cherchez
www.example.com/greeting/user/x/
a du sens pour moi. Concentrez-vous sur le fait de faire de votre demande de repos une sorte de phrase substantive -- un chemin à travers une hiérarchie (ou taxonomie, ou répertoire). Utilisez les noms les plus simples possible, en évitant les phrases de noms si possible.
généralement, les phrases composées signifient généralement un autre pas dans votre hiérarchie. Si vous n'avez pas /hello-world/user/ et /hello-universe/user/ . Vous avez /hello/world/user/ et hello/universe/user/ . Ou éventuellement /world/hello/user/ et /universe/hello/user/ .
le but est de fournir un chemin de navigation entre les ressources.
'UserId' est entièrement la mauvaise approche. Le verbe (méthodes HTTP) et l'approche du nom est ce que Roy Fielding signifie pour l'architecture REST . Les noms sont soit:
- A Collection de choses
- Un chose
Une bonne convention de nommage est:
[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
où {media_type} est l'un de: JSON, xml, rss, pdf, png, même html.
Il est possible de distinguer la collection en ajoutant un " s " à la fin, comme:
'users.json' *collection of things*
'user/id_value.json' *single thing*
mais cela signifie que vous devez garder une trace de l'endroit où vous avez mis le 's' et où vous n'avez pas. Plus la moitié de la planète (asiatiques pour commencer) parle des langues sans pluriel explicite de sorte que L'URL est moins convivial pour eux.
Pas de. Le reste n'a rien à voir avec les conventions de nommage URI. Si vous incluez ces conventions dans votre API, hors bande, au lieu d'utiliser uniquement l'hypertexte, alors votre API n'est pas reposante.
pour en savoir plus, lisez http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
j'ai une liste de lignes directrices à http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html que nous avons utilisé dans prod. Les lignes directrices sont toujours discutables... Je pense que la cohérence est parfois plus importante que la perfection (s'il y a une telle chose).
Je ne pense pas que l'affaire camel soit la question dans cet exemple, mais j'imagine qu'une convention de nommage plus reposant pour l'exemple ci-dessus serait:
api.service.com/helloWorld/userId/x
plutôt que de rendre userId un paramètre de requête (ce qui est parfaitement légal) mon exemple dénote que la ressource, IMO, d'une manière plus reposante.
je dirais qu'il est préférable d'utiliser le moins de caractères spéciaux possible dans les URL REST. Un des avantages de REST est qu'il rend l ' "interface" pour un service facile à lire. Cas Camel ou cas Pascal est probablement bon pour les noms de ressources (utilisateurs ou utilisateurs). Je ne pense pas qu'il y ait vraiment de normes strictes autour du repos.
aussi, je pense que Gandalf a raison, il est généralement plus propre dans le repos de ne pas utiliser les paramètres de la chaîne de requête, mais au lieu de créer des chemins qui définir les ressources que vous souhaitez traiter.
si vous authentifiez Vos clients avec Oauth2 je pense que vous aurez besoin de underscore pour au moins deux de vos noms de paramètres:
- client_id
- client_secret
j'ai utilisé camelCase dans mon API REST (non encore publiée). En écrivant la documentation de L'API, j'ai pensé à tout changer en snake_case pour ne pas avoir à expliquer pourquoi les params Oauth sont snake_case alors que les autres params ne le sont pas.