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

Question

Lors de la création d'Api REST, existe-il des directives ou de facto des normes pour les conventions de nommage à l'intérieur de l'API (par exemple: URL de point de terminaison de composants de chemin, les paramètres querystring)? Sont chameau bouchons de la norme, ou des traits de soulignement? les autres?

Par exemple:

api.service.com/helloWorld/userId/x

ou

api.service.com/hello_world/user_id/x

Remarque: Ce n'est pas une question d'API RESTful de la conception, plutôt la convention de nommage des lignes directrices à utiliser pour l'éventuel chemin de composants et/ou des paramètres de chaîne de requête utilisé.

Toutes les lignes directrices seraient appréciés.

Answer 1

Je pense que vous devriez éviter les casquettes de chameau, comme URL ne sont pas sensibles à la casse. La norme est d’utiliser des lettres minuscules. J’ai aussi éviter les traits de soulignement et utiliser des tirets à la place

Si votre URL devrait ressembler à ceci (en ignorant les problèmes de conception que vous avez demandé  :-))

Answer 2

L’API REST pour dropbox, twitter, google maps et facebook tous utilise des traits de soulignement.

Answer 3

Regardez de près d'URI pour le commun des ressources sur le web. Ceux-ci sont à votre modèle. Pensez répertoire des arbres; utilisation simple Linux-comme les noms de fichier et répertoire.

HelloWorld n'est pas une très bonne classe 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 pourrait être un nom que vous allez la chercher. Il est douteux, cependant, que le résultat de votre requête est seulement 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 avez à aller chercher de

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

Fait sens pour moi. Concentrer sur votre REPOS, de demander un type de syntagme nominal -- un chemin à travers une hiérarchie (ou taxonomie, ou le répertoire). L'utilisation la plus simple des noms possible, en évitant les expressions nominales, si possible.

Généralement, nom composé de phrases signifient généralement une autre étape de votre hiérarchie. Si vous n'avez pas d' /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 point est de fournir un chemin de navigation entre les ressources.

Answer 4

'UserId' est entièrement la mauvaise approche. Le Verbe (HTTP) et le Substantif approche est ce que Roy Fielding signifiait pour Le RESTE de l'architecture. Les Noms sont soit:

1. Une Collection de choses
2. Une 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_typ}

{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_typ}/{var}/{value}/more-var-value-pairs}

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

Où {media_type} est l'une des: json, xml, rss, pdf, png, 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 de la moitié de la planète (les Asiatiques pour commencer) parle les langues sans l'accord au pluriel si l'URL est moins convivial.

Answer 5

Lol RESTE n’a rien à voir avec les conventions d’affectation de noms d’URI. Si vous incluez ces conventions dans le cadre de votre API, out-of-band, au lieu de seulement via l’hypertexte, puis votre API n’est pas réparateur.

Pour plus d’informations, consultez http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven