REST url-Pfad-parameter Namenskonventionen

Hier ist ein zusätzliches paar von Konventionen in Bezug auf links und Pfade design in REST-APIs, die helfen könnten:

1. Pfad Params vs Query-String

• Pfad params (/parent/child1;child2) sind cool, aber-query-strings Ausdrücken können, so viel wie Pfad, params können, sind standard und explicit. ex:
  • /parent?id=child1&id=child2
  • oder /parent?id=child1;child2 ...etc

2. Plural oder singular

Verwendung von Pluralformen für jede Sammlung (oder-Tabelle oder-Ordner) ist gut, da es bedeutet, dass die Ressource ist eine Liste von anderen Ressourcen

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

Nesting-Ressource : Standardmäßig ohne Schachteln, es sei denn, es gibt eine starke Beziehung

Wenn ein Kandidat untergeordnete Ressource vorhanden sein können, unabhängig von den Eltern, es gibt keinen Punkt, in Schachteln, weil Sie könnte Ende-up mit mehrere Pfade für die selbe Sache :

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

Mit letzterem können Sie all den rest :

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

3. Verwenden Sie nisten nur auf starke Beziehungen

Wenn die geschachtelte Ressource nicht existiert außerhalb der Eltern (Zusammensetzung in der UML-Begriffe, zum Beispiel)

• /books/{book}/pages/{page} Du wäre schauen nie für eine Seite ohne die Angabe eines Buches
• /players/{player}/stats} (wieder, es hängt davon ab, Ihre domain-Modelle)

4. Naja ok... verschachtelte Pfade, die auf nicht so starke Beziehungen zu, sondern behandeln diese als Aliase

Natürlich möchten Sie vielleicht zu tun verschachteln, auch wenn es keine starke Beziehung, oder gebunden resource lifecycle (Abteilung/Mitarbeiter Beispiel) für einige Grund (DX, Lesbarkeit vielleicht ?). wenn Sie das tun, vielleicht sollten Sie die verschachtelten Pfad ein alias nur :

• für /departments/{department}/employees
• internen rewrite /employees?department={department}

5. Wenn Sie möchten, HATEOAS, dann Weg design sollte nicht die oberste Priorität

Auf der anderen Seite, client Lesbarkeit ist nicht wichtig, wenn Sie wollen, Sie zu umarmen, REST ist HATEOAS. API-clients sollten nicht erraten, Ihren links oder Ihren Vorlagen hartcodiert. Stattdessen API enthält links, die den Kunden Folgen. Beispiel:

Den root-Pfad könnte zum Beispiel eine Liste aller primären links:

GET /

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

Die links sind absichtlich hässlich in diesem Beispiel. Die eine formschlüssige Mitarbeiter ist eigentlich ein URL-Vorlage mit optionalen Parametern.

Die client-API dann aussieht, für den link mit Schlüssel employee (in diesem Fall /url-für-Arbeitnehmer) — unabhängig davon, was es sieht aus und nennt es:

GET /url-for-employees

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

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

Beachten Sie den Link-header enthält 2 links, einen für die Suche
und, um die nächste Seite der Mitarbeiter (rel=next").

Vorteile HATEOS sind out-of-scope-hier aber mindestens eine ist, dass Sie frei sind zu re-organisieren Sie Ihre Pfade, ohne zu brechen-API-clients

5. Letzte, versuchen, die Dinge auf Ihr Dateisystem

Könnte man die Datei system Skizze/mock einen Erholsamen API:
Ordner erstellen, Dateien (und vielleicht auch Verknüpfungen/Aliase/Verknüpfungen) auf Ihre Festplatte, wechseln, ändern, waschen, Spülen und wiederholen, bis Ihr zufrieden mit der Struktur 🙂

$ 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