Existe-t-il des directives de convention de dénomination pour les API REST? [fermé]

Lors de la création d'API REST, existe-t-il des directives ou des normes de facto pour les conventions de dénomination au sein de l'API (par exemple: composants de chemin de point de terminaison d'URL, paramètres de chaîne de requête)? Les casquettes de chameau sont-elles la norme ou soulignent-elles? 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 plutôt des directives de convention de dénomination à utiliser pour les éventuels composants de chemin 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 casquettes de chameau. La norme consiste à utiliser des lettres minuscules. Je voudrais également éviter les tirets bas et utiliser des tirets à la place

Votre URL devrait donc ressembler à ceci (en ignorant les problèmes de conception comme vous l'avez demandé :-))

api.service.com/hello-world/user-id/x

L'API REST pour Dropbox , Twitter , Google Web Services et Facebook utilise tous des traits de soulignement.

Examinez attentivement les URI pour les ressources Web ordinaires. Ce sont vos modèles. Pensez aux arborescences de répertoires; utilisez des noms de fichiers et de répertoires similaires à Linux.

HelloWorldn'est pas vraiment une bonne classe de ressources. Cela ne semble pas être une "chose". C'est possible, mais ce n'est pas très semblable à un nom. A greetingest une chose.

user-idpourrait être un nom que vous récupérez. Il est cependant douteux que le résultat de votre demande soit uniquement un user_id. Il est beaucoup plus probable que le résultat de la demande soit un utilisateur. Par conséquent, userest le nom que vous récupérez

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

Ça a du sens pour moi. Concentrez-vous sur le fait de faire de votre demande REST une sorte de locution - un chemin à travers une hiérarchie (ou taxonomie ou répertoire). Utilisez les noms les plus simples possibles, en évitant si possible les phrases nominales.

Généralement, les phrases nominales composées signifient généralement une autre étape dans votre hiérarchie. Vous n'avez donc pas /hello-world/user/et /hello-universe/user/. Vous avez /hello/world/user/et hello/universe/user/. Ou peut /world/hello/user/- être et /universe/hello/user/.

Il s'agit de fournir un chemin de navigation entre les ressources.

'UserId' est totalement la mauvaise approche. L'approche Verb (méthodes HTTP) et Noun est ce que Roy Fielding signifiait pour l' architecture REST . Les noms sont soit:

1. Une collection de choses
2. Une chose

Une bonne convention de dénomination 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 savoir où vous avez mis le «s» et où vous ne l'avez pas fait. De plus, la moitié de la planète (Asiatiques pour commencer) parle des langues sans pluriels explicites, donc l'URL leur est moins conviviale.

Non. REST n'a rien à voir avec les conventions de dénomination d'URI. Si vous incluez ces conventions dans votre API, hors bande, au lieu de seulement via l'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 sur http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html que nous avons utilisées dans prod. Les directives sont toujours discutables ... Je pense que la cohérence est parfois plus importante que de rendre les choses parfaites (s'il y en a une).

Je ne pense pas que le cas des chameaux soit le problème dans cet exemple, mais j'imagine qu'une convention de dénomination plus RESTful pour l'exemple ci-dessus serait:

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énote cette ressource, IMO, d'une manière plus RESTful.

Si vous authentifiez vos clients avec Oauth2, je pense que vous aurez besoin de souligner pour au moins deux de vos noms de paramètres:

• identité du client
• client_secret

J'ai utilisé camelCase dans mon (non encore publiée) API REST. En écrivant la documentation de l'API, j'ai pensé à tout changer pour snake_case, donc je n'ai pas à expliquer pourquoi les paramètres Oauth sont snake_case alors que d'autres paramètres ne le sont pas.

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

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 rend "l'interface" d'un service facile à lire. Le cas Camel ou 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 de REST.

De plus, je pense que Gandalf a raison, il est généralement plus propre dans REST de ne pas utiliser les paramètres de chaîne de requête, mais de créer des chemins qui définissent les ressources que vous souhaitez traiter.

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