Frage Namenskonventionen für den Namen des ReST-URL-Pfadparameters


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?

Vielen Dank.


8
2017-10-14 09:28


Ursprung


Antworten:


Im Folgenden finden Sie einige weitere Konventionen für die Gestaltung von Links und Pfaden in REST-APIs, die hilfreich sein könnten:

1. Pfadparameter vs Query String

  • Pfadparameter (/parent/child1;child2) sind cool, aber Query Strings können so viel ausdrücken, wie Path Params können, sind Standard und explizit. Ex:
    • /parent?id=child1&id=child2
    • oder /parent?id=child1;child2 ...etc

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 anderer Ressource ist

/users , /users/user1, /users?active=true

Nesting resource: Standard bis keine Verschachtelung, außer 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 verwenden:

  • /departments/{departments}/employees/{employee}
  • /branch-offices/{branch}/employees/{employee}
  • /employees/{employee}

Mit letzterem kannst du den Rest machen:

  • alle Mitarbeiter in einer Abteilung /employees?department={department}
  • alle Mitarbeiter in einer Filiale /employees?branch={branch}

3. Verwenden Sie die Verschachtelung nur bei starken Beziehungen

Wenn die verschachtelte Ressource nicht außerhalb des übergeordneten Elements vorhanden sein kann (Zusammensetzung zum Beispiel in UML-Begriffen)

  • /books/{book}/pages/{page} Sie würden niemals nach einer Seite suchen, ohne ein Buch anzugeben
  • /players/{player}/stats} (Auch hier kommt es auf Ihre Domain-Modelle an)

4. Gut, ok ... Verwenden Sie geschachtelte Pfade auf nicht so starke Beziehungen, aber behandeln Sie sie als Aliase

Natürlich möchten Sie vielleicht eine Verschachtelung durchführen, auch wenn es keine starke Beziehung gibt, oder einen gebundenen Ressourcen-Lebenszyklus (das Abteilungs / Mitarbeiter-Beispiel) aus irgendeinem Grund (DX, Lesbarkeit vielleicht?). Wenn Sie dies tun, sollten Sie den verschachtelten Pfad möglicherweise nur als Alias ​​betrachten:

  • zum /departments/{department}/employees
  • internes Neuschreiben /employees?department={department}

5. Wenn Sie HATEOAS wollen, dann sollte Pfaddesign nicht die oberste Priorität sein

Auf der anderen Seite ist die Lesbarkeit der Clients nicht wichtig, wenn Sie RESTs integrieren möchten Hateonen. 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 beispielsweise alle primären Links auflisten:

GET /

200 OK
Content-Type: application/json
{
   links:{
       "employees":"/url-for-employees{?department,branch,name}"
       "departments":"/them-deps"
   }
}

Die Links sind in diesem Beispiel absichtlich hässlich. Der eine Schlüssel Angestellte ist eigentlich ein URL-Vorlage mit optionalen Parametern.

Die Client-API sucht dann nach der Verbindung mit dem Schlüssel employee , (in diesem Fall / URL-für-Mitarbeiter) - unabhängig davon, wie es aussieht - und ruft es auf:

GET /url-for-employees

200 OK
Content-Type: application/json
Link: </url-for-employees{?department,branch,name}>; rel="search",
</url-for-employees?page=2>; rel="next"

['body is an array containing the first set/page of employees']

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 davon ist, 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: Erstelle Ordner, Dateien (und vielleicht auch Symlinks / Aliase / Shortcuts) auf deiner Festplatte, blättere sie durch, ändere sie, spüle sie ab und wiederhole, bis du mit der Struktur zufrieden bist :)

$ mkdir myapi
$ cd myapi
$ touch index.json
$ mkdir employees
$ touch employees/index.json
$ touch employees/smith.json
$ mkdir departments
$ touch departments/index.json
$ touch departments/accounting.json
$ mkdir departments/accounting
$ mkdir departments/accounting/employees
$ ln -s employees/smith.json departments/accounting/employees/smith.json
$ ls -l departments/accounting/employees
smith.json -> employees/smith.json

11
2018-03-22 15:19



Überprüfen Sie den Abschnitt Ressourcen-URI Beispiele für Naming Convention Tutorial. Hoffe, du wirst deine Antwort bekommen.

Auch das Buch  definiert drei Grundregeln für das URL-Design, die als Ausgangspunkt dienen:

• Verwenden Sie Pfadvariablen zum Codieren der Hierarchie: / parent / child

• Setzen Sie Interpunktionszeichen in Pfadvariablen, um eine Implizierung zu vermeiden   Hierarchie, wo keine existiert: / Eltern / Kind1; Kind2

• Verwenden Sie Abfragevariablen, um Eingaben in einen Algorithmus zu implizieren, zum Beispiel:   / Suche? q = Qualle & Start = 20

Weitere Richtlinien umfassen:

• URIs sollten sich im Idealfall nicht ändern.

• Dienste, die eine eindeutig identifizierbare Ressource über einen Schlüssel anbieten, sollten   Verwenden Sie die grundlegende Ruhe-Notation (z. B. / accounts / (account))

• Dienste mit optionalen Such- / Filterfunktionen sollten verwendet werden   Abfrageparameter? Schlüssel1 = Wert & Schlüssel2 = Wertnotation (z.B.   / Instrumente? Ticker = FT)

• Dienste, die obligatorische Argumente über GET erwarten, sollten sie als   Pfadvariablen (z. B. / accounthistory / (fromdate) / (todate)

• Alle Namen von Restdiensten sollten strenge Low-Case-Namen verwenden (z.   /Klient)

• 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.


3
2017-10-14 09:43