Existe-t-il des règles de convention de dénomination pour les API REST?
Lors de la création de REST API, existe-t-il des directives ou des normes de facto concernant les conventions de dénomination au sein de l'API (par exemple: composants de chemin d'accès aux points de terminaison d'URL, paramètres de chaîne de requête)? Les chameaux sont-ils la norme ou les soulignés? autres?
Par exemple:
api.service.com/helloWorld/userId/x
ou
api.service.com/hello_world/user_id/x
Remarque: Il ne s'agit pas de la conception de l'API RESTful, mais des règles de convention de dénomination à utiliser pour les éventuels composants de chemin d'accès et/ou les paramètres de chaîne de requête utilisés.
Toutes les directives seraient appréciées.
Je pense que vous devriez éviter les bonnets de chameau. La norme est d'utiliser des lettres minuscules. Je voudrais aussi éviter les traits de soulignement et utiliser des tirets à la place
Donc, votre URL devrait ressembler à ceci (en ignorant les problèmes de conception comme vous l'avez demandé :-))
api.service.com/hello-world/user-id/x
Examinez attentivement les adresses Web pour les ressources Web ordinaires. Ce sont votre modèle. Pensez aux arbres de répertoires; utilisez des noms de fichiers et de répertoires simples, de type Linux.
HelloWorld n'est pas une très bonne classe de ressources. Cela ne semble pas être une "chose". C'est peut-être le cas, mais ce n'est pas très semblable à un nom. Un greeting est une chose.
user-id pourrait être un nom que vous allez chercher. Il est toutefois douteux que le résultat de votre demande ne soit qu'un user_id. Il est beaucoup plus probable que le résultat de la demande est un utilisateur. Par conséquent, user est le nom que vous allez chercher
www.example.com/greeting/user/x/
Cela a du sens pour moi. Concentrez-vous sur votre requête REST comme une sorte de phrase nominale - un chemin dans une hiérarchie (ou une taxonomie, ou un répertoire). Utilisez les noms les plus simples possibles, en évitant les expressions nominales si possible.
Généralement, les expressions nominales composées signifient généralement une autre étape de votre hiérarchie. Donc 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.
L'API REST pour Dropbox , Twitter , Services Web Google et Facebook tous les soulignements utilisés .
"UserId" est totalement la mauvaise approche. L'approche verbale (méthodes HTTP) et nom est ce que Roy Fielding voulait dire pour l'architecture REST . Les noms sont soit:
- A Collection de choses
- A thing
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 des formats suivants: json, xml, rss, pdf, png, voire 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 savoir où vous avez mis le 's' et où vous ne l'avez pas encore fait. Plus la moitié de la planète (les Asiatiques pour commencer) parle des langues sans pluriels explicites, l’URL leur est donc moins conviviale.
Non. REST n'a rien à voir avec les conventions de dénomination d'URI. Si vous incluez ces conventions dans votre API, en dehors de la bande, au lieu de le faire uniquement par hypertexte, votre API n'est pas RESTful.
Pour plus d'informations, voir http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
Les noms de domaine ne sont pas sensibles à la casse, mais le reste de l'URI peut certainement l'être. C'est une grosse erreur de supposer que les URI ne sont pas sensibles à la casse.
J'ai une liste de directives à http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html que nous avons utilisé dans prod. Les directives sont toujours discutables ... Je pense que la cohérence est parfois plus importante que l’obtention de la perfection (s’il en existe une).
Je ne pense pas que le cas des chameaux soit le problème dans cet exemple, mais j'imagine qu'une convention de nommage plus reposante pour l'exemple ci-dessus serait la suivante:
api.service.com/helloWorld/userId/x
plutôt que de faire de userId un paramètre de requête (ce qui est parfaitement légal), mon exemple désigne cette ressource dans, IMO, de manière plus RESTful.
Si vous authentifiez vos clients avec Oauth2, je pense que vous aurez besoin de soulignement pour au moins deux de vos noms de paramètres:
- identité du client
- client_secret
J'ai utilisé camelCase dans mon API (pas encore publiée) REST. Lors de la rédaction de la documentation de l'API, j'ai envisagé de tout changer en snake_case. Je n'ai donc pas à expliquer pourquoi les paramètres Oauth sont snake_case alors que les autres paramètres ne le sont pas.
Je dirais qu'il est préférable d'utiliser le moins de caractères spéciaux possible dans les URL REST. L'un des avantages de REST est qu'il facilite la lecture de "l'interface" d'un service. Le cas Camel ou Pascal est probablement bon pour les noms de ressources (Utilisateurs ou utilisateurs). Je ne pense pas qu'il existe vraiment de normes strictes autour de REST.
De plus, je pense que Gandalf a raison, il est généralement plus propre dans REST de ne pas utiliser de paramètres de chaîne de requête, mais de créer des chemins qui définissent les ressources que vous souhaitez gérer.