Gibt es Namenskonventionen für generische Parameternamen in der ReST-URL?
In meinem Beispiel möchte ich die Adresse einer Abteilung basierend auf der Abteilungs-ID oder der Organisations-ID erhalten, unter die die Abteilung fällt.
Also der URL-Pfad-Parametername deptOrOrgId - ist es gültig basierend auf den Namenskonventionen oder Soll ich einen generischen Namen wie sectionID oder officeID oder etwas verwenden, um sowohl die Abteilungs ID als auch die Organisations ID darzustellen?
Danke.
Im Folgenden finden Sie einige zusätzliche Konventionen für die Gestaltung von Links und Pfaden in REST-APIs, die hilfreich sein könnten:
1. Pfadparameter vs Abfragezeichenfolge
/parent/child1;child2 ) sind cool, aber Abfragezeichenfolgen können so viel ausdrücken, wie Pfadparameter, Standard und explizit sein können. Ex:
/parent?id=child1&id=child2 /parent?id=child1;child2 ... usw. 2. Plural oder Singular
Das Verwenden von Plural für jede Sammlung (oder Tabelle oder Ordner) ist gut, da es bedeutet, dass die Ressource eine Liste der anderen Ressource ist
/users , /users/user1 , /users?active=true
Sammelform-Ressource: Standard bis keine Verschachtelung, es sei denn, es gibt eine starke Relation
Wenn eine untergeordnete Kandidatenressource unabhängig vom übergeordneten Element vorhanden sein kann, hat das Verschachteln keinen Sinn, da Sie möglicherweise mehrere Pfade für dasselbe Objekt haben:
/departments/{departments}/employees/{employee} /branch-offices/{branch}/employees/{employee} /employees/{employee} Mit letzterem kannst du den ganzen Rest machen:
/employees?department={department}
/employees?branch={branch}
3. Verwenden Sie die Verschachtelung nur für starke Relationen
Wenn die verschachtelte Ressource nicht außerhalb des übergeordneten Elements ( Komposition in UML-Termini zum Beispiel vorhanden sein kann)
/books/{book}/pages/{page} Sie würden niemals nach einer Seite suchen, ohne ein Buch anzugeben /players/{player}/stats} (wiederum hängt es von Ihren Domänenmodellen ab) 4. Nun gut ... Verwenden Sie geschachtelte Pfade auch für nicht so starke Beziehungen, aber behandeln Sie sie als Aliase
Natürlich möchten Sie vielleicht eine Verschachtelung durchführen, auch wenn es keine feste Beziehung oder einen gebundenen Ressourcen-Lebenszyklus (das Beispiel Abteilung / Mitarbeiter) gibt (DX, Lesbarkeit vielleicht?). Wenn Sie dies tun, sollten Sie den verschachtelten Pfad möglicherweise nur als einen Alias betrachten:
/departments/{department}/employees
/employees?department={department}
5. Wenn Sie HATEOAS möchten, sollte Pfaddesign nicht die oberste Priorität sein
Andererseits ist die Lesbarkeit des Clients nicht wichtig, wenn Sie die HATEOAS von REST nutzen möchten. API-Clients sollten Ihre Links nicht erraten oder ihre Vorlagen fest codieren lassen. Stattdessen stellt Ihre API Links bereit, denen die Clients folgen. Beispiel:
Der Root-Pfad könnte zum Beispiel alle primären Links auflisten:
%Vor%Die Links sind in diesem Beispiel absichtlich hässlich. Die one keyed Mitarbeiter ist eigentlich eine URL-Vorlage mit optionalen Parametern.
Die Client-API sucht dann nach der Verknüpfung mit dem Schlüssel employee (in diesem Fall / url-for-employees) - unabhängig davon, wie sie aussieht - und ruft sie auf:
Beachten Sie den Link-Header mit 2 Links, einen für die Suche und eine, um die nächste Seite von Mitarbeitern zu erhalten (rel = next ").
Die Vorteile von HATEOS sind hier nicht vorgesehen, aber mindestens eine Möglichkeit, dass Sie Ihre Pfade neu organisieren können, ohne die API-Clients zu beschädigen
5. Versuchen Sie zuletzt Dinge in Ihrem Dateisystem
Man könnte das Dateisystem verwenden, um eine RESTfull-API zu skizzieren / nachzubilden: Erstellen Sie Ordner, Dateien (und vielleicht Symlinks / Aliase / Shortcuts) auf Ihrer Festplatte, durchsuchen Sie sie, ändern Sie sie, spülen Sie sie aus und wiederholen Sie sie, bis Sie mit der Struktur zufrieden sind:)
%Vor%Überprüfen Sie den Abschnitt Resource URI Beispiele für Tutorial zur Benennungskonvention . Hoffe, du wirst deine Antwort bekommen.
Auch das Buch definiert drei Grundregeln für das URL-Design, die als guter Ausgangspunkt dienen:
• Verwenden Sie Pfadvariablen zum Codieren der Hierarchie: / parent / child
• Platzieren Sie Interpunktionszeichen in Pfadvariablen, um eine Implizierung zu vermeiden Hierarchie, wo keine existiert: / parent / child1; child2
• Verwenden Sie Abfragevariablen, um Eingaben in einen Algorithmus zu implizieren, zum Beispiel: / search? q = quallen & amp; start = 20
Weitere Richtlinien umfassen:
• URIs sollten idealerweise im Laufe der Zeit nicht geändert werden.
• Dienste, die eine eindeutig identifizierbare Ressource über einen Schlüssel anbieten, sollten Verwenden Sie die Notennotation (z. B. / accounts / (account))
• Dienste mit optionalen Such- / Filterfunktionen sollten verwendet werden Abfrageparameter? Schlüssel1 = Wert & amp; key2 = Wertnotation (z.B. / Instrumente? Ticker = FT)
• Services, die obligatorische Argumente über GET erwarten, sollten sie als Pfadvariablen (z. B. / accounthistory / (fromdate) / (todate)
)• Alle Namen von Rest-Services sollten strenge Low-Case-Namen verwenden (z. / Client)
• Die Elemente der URI sollten Geschäftseinheiten und der Mapping sollte konsistent sein. Zum Beispiel eine Geschäftseinheit namens contentpartner sollte durchweg als Contentpartner bezeichnet werden in allen URIs (anstatt einer Mischung aus Partner, CP usw.). Ein guter Anfang Punkt wäre der Name des Domänenobjekts.
• Parameter, die keine Ressource definieren, sie jedoch qualifizieren (z. B. Gebietsschema was in die Übersetzungen der Daten einfließt) sollte nicht Bestandteil von sein der normale URI-Bereich. Erwägen Sie die Verwendung von Headern oder einer optionalen Abfrage Parameter für diese
• Verwenden Sie Substantive, keine Verben. Die Kraft von REST kommt durch die Tatsache Es gibt eine begrenzte Verbmenge (Operationen) kombiniert mit einer großen Menge von Substantive (oder Ressourcen). Folglich die Art, in der diese Substantive sind konstruiert ist von großer Bedeutung.
• Vermeiden Sie Suffixe. Beim Entwerfen von URLs ist es wichtig, dass sie sich darauf beziehen zu dem Ding, an dem gearbeitet wird, statt zur Operation durchgeführt werden. Zweitens interessiert sich der Kunde für die Ressource - nicht die Implementierung der Serversoftware, die den Dienst antreibt. Es ist wünschenswert, Suffixe wie .jsp oder .aspx zu vermeiden.
• Verwenden Sie Akzeptiert Header für die Inhaltsverhandlung
• Halten Sie es intuitiv. URIs sollten für Menschen lesbar oder erratbar sein. Das Der einfachste Weg, dies zu tun, ist eine URI-Hierarchie zu erstellen, Gruppierung verwandte Artikel zusammen. Solche Muster der Kategorie und Unterkategorie sind sehr einfach zu verstehen.
Tags und Links rest