it-swarm.com.de

Gibt es Richtlinien für Namenskonventionen für REST APIs?

Gibt es beim Erstellen von REST APIs) Richtlinien oder Defacto-Standards für Namenskonventionen in der API (z. B. URL-Endpunktpfadkomponenten, Abfragezeichenfolgeparameter)? Sind Kamelkappen die Norm oder Unterstriche? Andere?

Beispielsweise:

api.service.com/helloWorld/userId/x

oder

api.service.com/hello_world/user_id/x

Hinweis: Dies ist keine Frage des RESTful API-Designs, sondern der Namenskonventionsrichtlinien, die für die eventuell verwendeten Pfadkomponenten und/oder Abfragezeichenfolgenparameter verwendet werden.

Alle Richtlinien wäre dankbar.

204
jnorris

Ich denke, Sie sollten Kamelkappen vermeiden. Die Norm ist die Verwendung von Kleinbuchstaben. Ich würde auch Unterstriche vermeiden und stattdessen Bindestriche verwenden

Deine URL sollte also so aussehen (ignoriere die Designprobleme wie gewünscht :-))

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

Schauen Sie sich die URIs für gewöhnliche Webressourcen genau an. Das sind deine Vorlagen. Denken Sie an Verzeichnisbäume. Verwenden Sie einfache Linux-ähnliche Datei- und Verzeichnisnamen.

HelloWorld ist keine wirklich gute Ressourcenklasse. Es scheint kein "Ding" zu sein. Es mag sein, aber es ist nicht sehr nomenartig. Ein greeting ist eine Sache.

user-id ist möglicherweise ein Nomen, das Sie abrufen. Es ist jedoch zweifelhaft, dass das Ergebnis Ihrer Anfrage nur eine user_id ist. Es ist viel wahrscheinlicher, dass das Ergebnis der Anfrage ein Benutzer ist. Daher ist user das Nomen, das Sie abrufen

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

Für mich ergibt das Sinn. Konzentrieren Sie sich darauf, dass Sie REST eine Art Nomenphrase anfordern - einen Pfad durch eine Hierarchie (oder Taxonomie oder ein Verzeichnis). Verwenden Sie möglichst einfache Nomen und vermeiden Sie Nomenphrasen, wenn möglich.

Im Allgemeinen bedeuten zusammengesetzte Nominalphrasen normalerweise einen weiteren Schritt in Ihrer Hierarchie. Sie haben also nicht /hello-world/user/ und /hello-universe/user/. Du hast /hello/world/user/ und hello/universe/user/. Oder möglicherweise /world/hello/user/ und /universe/hello/user/.

Es geht darum, einen Navigationspfad zwischen den Ressourcen bereitzustellen.

82
S.Lott

Die REST API für Dropbox , Twitter , Google Web Services und Facebook Alle verwenden Unterstriche.

82
jz1108

'UserId' ist völlig der falsche Ansatz. Der Verb HTTP-Methoden) und Nomen-Ansatz ist das, wofür --- (Roy Fielding gedacht ist Die REST Architektur . Die Nomen sind entweder:

  1. Eine Sammlung von Dingen
  2. A thing

Eine gute Namenskonvention ist:

[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

Wobei {media_type} eine der folgenden Angaben ist: json, xml, rss, pdf, png und sogar html.

Es ist möglich, die Sammlung zu unterscheiden, indem am Ende ein 's' hinzugefügt wird, wie zum Beispiel:

'users.json' *collection of things*
'user/id_value.json' *single thing*

Dies bedeutet jedoch, dass Sie den Überblick behalten müssen, wo Sie die 's' abgelegt haben und wo nicht. Außerdem spricht die Hälfte des Planeten (Asiaten für Anfänger) Sprachen ohne explizite Pluralformen, sodass die URL für sie weniger freundlich ist.

29
Dennis

Nein. REST hat nichts mit URI-Benennungskonventionen zu tun. Wenn Sie diese Konventionen als Teil Ihrer API verwenden, ist Ihre API bandextern und nicht nur über Hypertext, sondern nicht REST-konform .

Weitere Informationen finden Sie unter http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

14
aehlke

Domain-Namen unterscheiden nicht zwischen Groß- und Kleinschreibung, der Rest der URI kann es jedoch sein. Es ist ein großer Fehler anzunehmen, dass bei URIs nicht zwischen Groß- und Kleinschreibung unterschieden wird.

9
rickoshay

Ich habe eine Liste von Richtlinien unter http://soaprobe.blogspot.co.uk/2012/10/soa-rest-service-naming-guideline.html , die wir in prod. Richtlinien sind immer umstritten ... Ich denke, Konsistenz ist manchmal wichtiger, als Dinge perfekt zu machen (wenn es so etwas gibt).

5
Robert Morschel

Ich glaube nicht, dass der Kamelfall das Problem in diesem Beispiel ist, aber ich stelle mir eine restvollere Namenskonvention für das obige Beispiel vor:

api.service.com/helloWorld/userId/x

anstatt userId zu einem Abfrageparameter zu machen (was vollkommen legal ist), zeigt mein Beispiel diese Ressource in IMO auf eine REST-gerechtere Weise an.

2
Gandalf

Wenn Sie Ihre Clients mit Oauth2 authentifizieren, benötigen Sie meines Erachtens einen Unterstrich für mindestens zwei Ihrer Parameternamen:

  • kunden ID
  • client_secret

Ich habe camelCase in meiner (noch nicht veröffentlichten) REST API verwendet. Beim Schreiben der API-Dokumentation habe ich darüber nachgedacht, alles in snake_case zu ändern, damit ich nicht erklären muss, warum die Oauth params sind snake_case, andere nicht.

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

1
Michael

Ich würde sagen, dass es vorzuziehen ist, so wenig Sonderzeichen wie möglich in REST URLs zu verwenden. Einer der Vorteile von REST ist, dass es die "Schnittstelle" macht Für einen Service, der einfach zu lesen ist, ist Camel Case oder Pascal Case wahrscheinlich gut für die Ressourcennamen (Benutzer oder Benutzer). Ich glaube nicht, dass es wirklich strenge Standards für REST gibt.

Ich denke auch, dass Gandalf Recht hat. Normalerweise ist es in REST) sauberer, keine Abfragezeichenfolgenparameter zu verwenden, sondern Pfade zu erstellen, die definieren, mit welchen Ressourcen Sie umgehen möchten.

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

0
Andy White