Gibt es Richtlinien für Namenskonventionen für REST-APIs? [geschlossen]

Gibt es beim Erstellen von REST-APIs Richtlinien oder Defacto-Standards für Namenskonventionen innerhalb der API (z. B. URL-Endpunktpfadkomponenten, Querystring-Parameter)? 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 Richtlinien für Namenskonventionen, die für die eventuell verwendeten Pfadkomponenten und / oder Abfragezeichenfolgenparameter verwendet werden sollen.

Alle Richtlinien wäre dankbar.

Ich denke, Sie sollten Kamelkappen vermeiden. Die Norm besteht darin, Kleinbuchstaben zu verwenden. Ich würde auch Unterstriche vermeiden und stattdessen Bindestriche verwenden

Ihre URL sollte also so aussehen (die von Ihnen angeforderten Designprobleme werden ignoriert :-))

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

Die REST-API für Dropbox , Twitter , Google Web Services und Facebook verwendet alle Unterstriche.

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

HelloWorldist keine wirklich gute Klasse von Ressourcen. Es scheint kein "Ding" zu sein. Es mag sein, aber es ist nicht sehr nomenartig. A greetingist eine Sache.

user-idkönnte ein Substantiv sein, das Sie holen. Es ist jedoch zweifelhaft, dass das Ergebnis Ihrer Anfrage nur eine Benutzer-ID ist. Es ist viel wahrscheinlicher, dass das Ergebnis der Anfrage ein Benutzer ist. Daher userist das Substantiv, das Sie abrufen

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

Für mich ergibt das Sinn. Konzentrieren Sie sich darauf, Ihre REST-Anfrage zu einer Art Nominalphrase zu machen - einem Pfad durch eine Hierarchie (oder Taxonomie oder ein Verzeichnis). Verwenden Sie möglichst einfache Substantive und vermeiden Sie nach Möglichkeit Nominalphrasen.

Im Allgemeinen bedeuten zusammengesetzte Nominalphrasen einen weiteren Schritt in Ihrer Hierarchie. Also hast du 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 Ressourcen bereitzustellen.

'UserId' ist völlig falsch. Der Verb- (HTTP-Methoden) und Nomen-Ansatz war das, was Roy Fielding für die REST-Architektur bedeutete . Die Substantive sind entweder:

1. Eine Sammlung von Dingen
2. Eine Sache

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} einer der folgenden ist: json, xml, rss, pdf, png, sogar html.

Es ist möglich, die Sammlung durch Hinzufügen eines 's' am Ende zu unterscheiden, wie zum Beispiel:

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

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

Nein. REST hat nichts mit URI-Namenskonventionen zu tun. Wenn Sie diese Konventionen als Teil Ihrer API außerhalb des Bandes und nicht nur über Hypertext einfügen, ist Ihre API nicht RESTful.

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

Domain-Namen unterscheiden nicht zwischen Groß- und Kleinschreibung, der Rest der URI jedoch durchaus. Es ist ein großer Fehler anzunehmen, dass URIs nicht zwischen Groß- und Kleinschreibung unterscheiden.

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

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

api.service.com/helloWorld/userId/x

Anstatt userId zu einem Abfrageparameter zu machen (was vollkommen legal ist), bezeichnet mein Beispiel diese Ressource in IMO auf eine REST-fähigere Weise.

Wenn Sie Ihre Clients mit Oauth2 authentifizieren, benötigen Sie wahrscheinlich 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-Parameter snake_case sind, während andere Parameter dies nicht sind.

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

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

Ich denke auch, dass Gandalf Recht hat. In REST ist es normalerweise 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