REST API Ressourcennamen: Singular oder Plural?

TL;DR

REST-API-Ressourcennamen sollten im Plural stehen. Verwenden Sie /pets/{id}, nicht /pet/{id}. Pluralnamen repräsentieren Sammlungen konsistent, stimmen mit der HTTP-Semantik überein und passen dazu, wie Entwickler über Ressourcen denken. Die moderne PetstoreAPI verwendet durchweg Pluralnamen in ihrem API-Design und folgt damit den Best Practices der Branche.

Einleitung

Sie entwerfen eine REST-API. Sie benötigen einen Endpunkt, um einen Benutzer anhand der ID abzurufen. Verwenden Sie /user/123 oder /users/123? Diese Frage hat unzählige Debatten, Stack-Overflow-Threads und Team-Streitigkeiten ausgelöst.

Die Antwort ist klar: Verwenden Sie den Plural. Aber das Verständnis des Warums ist wichtiger als das Auswendiglernen der Regel. Die Begründung bezieht sich darauf, wie REST funktioniert, wie sich Sammlungen verhalten und wie Entwickler über Ressourcen denken.

Der alte Swagger Petstore hat dies falsch gemacht und /pet/{id} anstelle von /pets/{id} verwendet. Diese Inkonsistenz lehrte Millionen von Entwicklern das falsche Muster. Die moderne PetstoreAPI behebt dies, indem sie durchweg Pluralnamen für alle Endpunkte verwendet.

💡

Wenn Sie REST-APIs entwickeln oder testen, hilft Apidog Ihnen, Ressourcennamenkonventionen zu validieren, die Endpunktkonsistenz zu prüfen und sicherzustellen, dass Ihre API den REST-Best Practices folgt. Sie können OpenAPI-Spezifikationen importieren, Namensmuster überprüfen und Inkonsistenzen erkennen, bevor sie in Produktion gehen.

Schaltfläche

In diesem Leitfaden erfahren Sie, warum Pluralnamen die richtige Wahl sind, wie sie mit den REST-Prinzipien übereinstimmen und wie Sie sie korrekt implementieren, wobei die moderne PetstoreAPI als Referenz dient.

Die Debatte Plural vs. Singular

Die Debatte existiert, weil beide Ansätze auf den ersten Blick logisch erscheinen.

Das Singular-Argument

„Wenn ich /user/123 anfordere, erhalte ich einen Benutzer, nicht mehrere Benutzer. Singular macht Sinn.“

Diese Argumentation konzentriert sich auf die Antwort – Sie erhalten eine einzelne Ressource, daher sollte die URL im Singular stehen.

Das Plural-Argument

„Die URL repräsentiert eine Sammlung. /users ist die Sammlung aller Benutzer. /users/123 ist Element 123 in dieser Sammlung.“

Diese Argumentation konzentriert sich auf die Ressourcenstruktur – URLs repräsentieren Sammlungen, und Sie greifen auf Elemente innerhalb dieser Sammlungen zu.

Warum das wichtig ist

Ihre Wahl beeinflusst:

API-Konsistenz – Gemischte Benennung verwirrt Entwickler
Mentale Modelle – Wie Entwickler Ihre API-Struktur verstehen
Codegenerierung – Tools generieren Client-Code basierend auf Ressourcennamen
Klarheit der Dokumentation – Die Dokumentation muss Ihre Benennungslogik erklären

Warum Pluralnamen gewinnen

Plural-Ressourcennamen stimmen mit REST-Prinzipien und HTTP-Semantik überein. Hier ist der Grund.

1. Sammlungen sind im Plural

In REST sind Ressourcen Sammlungen. Wenn Sie auf /users zugreifen, greifen Sie auf die Benutzer-Sammlung zu. Wenn Sie auf /users/123 zugreifen, greifen Sie auf Element 123 in der Benutzer-Sammlung zu.

GET /users          ← Die Benutzer-Sammlung
GET /users/123      ← Element 123 in der Benutzer-Sammlung
POST /users         ← Zur Benutzer-Sammlung hinzufügen
DELETE /users/123   ← Element 123 aus der Benutzer-Sammlung entfernen

Dieses mentale Modell ist konsistent. Die Sammlung ist immer /users, egal ob Sie auf alle Elemente oder nur ein Element zugreifen.

Bei Singularnamen bricht das mentale Modell zusammen:

GET /user           ← Welcher Benutzer?
GET /user/123       ← Das macht Sinn
POST /user          ← Hinzufügen zu... was?

2. HTTP-Methoden operieren auf Sammlungen

HTTP-Methoden beschreiben Operationen auf Sammlungen:

GET /users – Die Sammlung abrufen
POST /users – Zur Sammlung hinzufügen
GET /users/123 – Element 123 aus der Sammlung abrufen
PUT /users/123 – Element 123 in der Sammlung ersetzen
DELETE /users/123 – Element 123 aus der Sammlung entfernen

Die Sammlung ist die Ressource. Einzelne Elemente sind Mitglieder dieser Sammlung.

3. Konsistenz über Endpunkte hinweg

Pluralnamen schaffen Konsistenz:

GET /pets           ← Sammlung
GET /pets/123       ← Element in Sammlung
GET /orders         ← Sammlung
GET /orders/456     ← Element in Sammlung

Singularnamen zwingen Sie dazu, zwischen Singular und Plural zu wechseln:

GET /pet            ← Macht keinen Sinn
GET /pet/123        ← Macht Sinn
GET /pets           ← Moment, jetzt ist es Plural?

4. Industriestandards

Große APIs verwenden Pluralnamen:

GitHub-API: /repos, /users, /issues
Stripe-API: /customers, /charges, /subscriptions
Twilio-API: /accounts, /messages, /calls
Google-APIs: /users, /groups, /files

Die moderne PetstoreAPI folgt diesem Standard mit /pets, /orders, /users.

Das mentale Modell der Sammlung

Das Verständnis von Sammlungen hilft Ihnen, bessere APIs zu entwerfen.

Sammlungen in REST

Eine Sammlung ist eine Menge von Ressourcen. In einer Tierhandlungs-API:

/pets – Die Sammlung aller Haustiere
/orders – Die Sammlung aller Bestellungen
/users – Die Sammlung aller Benutzer

Jede Sammlung unterstützt Operationen:

GET /pets           ← Haustiere auflisten (mit Filterung, Paginierung)
POST /pets          ← Neues Haustier erstellen
GET /pets/{id}      ← Ein bestimmtes Haustier abrufen
PUT /pets/{id}      ← Ein bestimmtes Haustier aktualisieren
DELETE /pets/{id}   ← Ein bestimmtes Haustier löschen

Unter-Sammlungen

Sammlungen können Unter-Sammlungen enthalten:

GET /pets/{id}/photos           ← Foto-Sammlung für Haustier {id}
POST /pets/{id}/photos          ← Foto zu Haustier {id} hinzufügen
GET /pets/{id}/photos/{photoId} ← Spezifisches Foto

Das Muster bleibt konsistent: Sammlungen sind im Plural, Elemente werden über die ID abgerufen.

Beispiel der modernen PetstoreAPI

Die moderne PetstoreAPI implementiert dies korrekt:

GET /pets
GET /pets/{petId}
GET /pets/{petId}/photos
POST /pets/{petId}/vaccinations
GET /orders
GET /orders/{orderId}
GET /orders/{orderId}/items

Jede Sammlung steht im Plural. Jeder Elementzugriff verwendet {id} innerhalb dieser Sammlung.

Wie die moderne PetstoreAPI Pluralnamen verwendet

Sehen wir uns reale Beispiele der modernen PetstoreAPI an.

Haustier-Ressourcen

GET    /pets                    ← Alle Haustiere auflisten
POST   /pets                    ← Ein neues Haustier erstellen
GET    /pets/{petId}            ← Spezifisches Haustier abrufen
PUT    /pets/{petId}            ← Haustier aktualisieren
DELETE /pets/{petId}            ← Haustier löschen
GET    /pets?status=AVAILABLE   ← Haustiere nach Status filtern

Bestell-Ressourcen

GET    /orders                  ← Alle Bestellungen auflisten
POST   /orders                  ← Bestellung erstellen
GET    /orders/{orderId}        ← Spezifische Bestellung abrufen
PUT    /orders/{orderId}        ← Bestellung aktualisieren
DELETE /orders/{orderId}        ← Bestellung stornieren

Benutzer-Ressourcen

GET    /users                   ← Benutzer auflisten
POST   /users                   ← Benutzer erstellen
GET    /users/{userId}          ← Spezifischen Benutzer abrufen
PUT    /users/{userId}          ← Benutzer aktualisieren
DELETE /users/{userId}          ← Benutzer löschen

Verschachtelte Ressourcen

GET /pets/{petId}/photos                    ← Fotos des Haustiers
POST /pets/{petId}/photos                   ← Foto hinzufügen
GET /pets/{petId}/vaccinations              ← Impfungen des Haustiers
POST /pets/{petId}/vaccinations             ← Impfung erfassen
GET /orders/{orderId}/items                 ← Bestellpositionen

Die [vollständige REST-API-Dokumentation](https://docs.petstoreapi.com/protocols/rest) finden Sie in den vollständigen Endpunktlisten.

Häufige Argumente für den Singular (und warum sie falsch sind)

Betrachten wir gängige Argumente für Singularnamen.

Argument 1: „Die Antwort ist im Singular“

Behauptung: „Wenn ich /user/123 abrufe, erhalte ich einen Benutzer. Singular macht Sinn.“

Gegenargument: Die URL repräsentiert den Speicherort der Ressource, nicht die Antwort. /users/123 bedeutet „Element 123 in der Benutzer-Sammlung“. Die Tatsache, dass die Antwort im Singular ist, ändert nichts an der Sammlungsstruktur.

Argument 2: „Es liest sich im Code besser“

Behauptung: „getUser(id) liest sich besser als getUsers(id).“

Gegenargument: Ihre Client-Code-Benennung ist unabhängig von der URL-Struktur. Sie können haben:

// URL: GET /users/123
function getUser(id) {
  return api.get(`/users/${id}`);
}

Der Funktionsname muss nicht mit der URL übereinstimmen.

Argument 3: „Singular vermeidet grammatikalische Probleme“

Behauptung: „Was ist mit Ressourcen wie ‚status‘ oder ‚information‘, die keine klaren Plurale haben?“

Gegenargument: Dies sind normalerweise Singleton-Ressourcen, keine Sammlungen. Verwenden Sie den Singular für Singletons:

GET /status         ← Systemstatus (Singleton)
GET /configuration  ← App-Konfiguration (Singleton)
GET /users          ← Benutzer-Sammlung (Plural)

Argument 4: „Mein ORM verwendet Singular-Tabellennamen“

Behauptung: „Meine Datenbanktabellen sind im Singular (user, order), also sollte meine API dazu passen.“

Gegenargument: Ihr API-Design sollte keine Datenbankimplementierungsdetails preisgeben. REST-APIs repräsentieren Ressourcen, nicht Datenbanktabellen. Verwenden Sie den Plural für Sammlungen, unabhängig von Ihrem Datenbankschema.

Testen der Ressourcennamen mit Apidog

Apidog hilft Ihnen, Ressourcennamenkonventionen zu validieren und zu testen.

Moderne PetstoreAPI importieren

Importieren Sie die OpenAPI-Spezifikation der modernen PetstoreAPI
Apidog erkennt automatisch Ressourcenmuster
Überprüfen Sie die Endpunktbenennung auf Konsistenz

Tests für Namenskonventionen erstellen

// Apidog-Testskript
pm.test("Ressourcennamen sind im Plural", function() {
  const path = pm.request.url.getPath();
  const segments = path.split('/').filter(s => s);

  // Überprüfen, ob das erste Segment im Plural ist
  const resource = segments[0];
  pm.expect(resource).to.match(/s$/); // Endet mit 's'
});

Konsistenz validieren

Apidog kann prüfen:

Alle Sammlungs-Endpunkte verwenden Pluralnamen
Unterressourcen folgen demselben Muster
Kein Mischen von Singular/Plural in derselben API

Mit realen Anfragen testen

GET https://api.petstoreapi.com/v1/pets
GET https://api.petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24
GET https://api.petstoreapi.com/v1/orders

Apidog validiert Antworten und hilft Ihnen, die Namenskonsistenz über Ihre gesamte API hinweg sicherzustellen.

Grenzfälle und Ausnahmen

Einige Ressourcen passen nicht zum Pluralmuster.

Singleton-Ressourcen

Ressourcen, die nur einmal existieren, sollten im Singular stehen:

GET /status         ← Systemstatus
GET /configuration  ← App-Konfiguration
GET /health         ← Gesundheitsprüfung
GET /metrics        ← Systemmetriken

Dies sind keine Sammlungen, daher ist der Plural hier nicht anwendbar.

Controller-Ressourcen

Aktionen, die nicht zu CRUD-Operationen passen:

POST /login         ← Authentifizierungsaktion
POST /logout        ← Sitzungsbeendigung
POST /search        ← Komplexe Suchoperation

Dies sind akzeptable Ausnahmen, da sie Aktionen und keine Ressourcen repräsentieren.

Unzählbare Substantive

Einige Substantive haben keine klaren Plurale:

GET /information    ← Singular (unzählbar)
GET /data           ← Singular (unzählbar)
GET /equipment      ← Singular (unzählbar)

Verwenden Sie den Singular für unzählbare Substantive, aber diese sind in typischen APIs selten.

Ansatz der modernen PetstoreAPI

Die moderne PetstoreAPI behandelt diese Fälle:

# Sammlungen (Plural)
GET /pets
GET /orders
GET /users

# Singletons (Singular)
GET /health
GET /metrics

# Aktionen (Singularverben)
POST /login
POST /logout

Fazit

REST-API-Ressourcennamen sollten im Plural stehen. Dies stimmt mit der Sammlungssemantik, den HTTP-Methoden und Industriestandards überein. Die moderne PetstoreAPI demonstriert dieses Muster korrekt über alle Endpunkte hinweg.

Wichtige Erkenntnisse:

Verwenden Sie Pluralnamen für Sammlungen (/pets, /orders, /users)
Einzelne Elemente werden innerhalb von Sammlungen aufgerufen (/pets/123)
Singleton-Ressourcen können im Singular stehen (/status, /health)
Konsistenz ist wichtiger als Perfektion
Testen Sie Ihre Namenskonventionen mit Apidog

Die Debatte Plural vs. Singular ist geklärt. Befolgen Sie den Industriestandard, verwenden Sie Pluralnamen und erstellen Sie APIs, die Entwickler intuitiv verstehen.

Nächste Schritte:

Überprüfen Sie Ihre API-Endpunkte auf Namenskonsistenz
Überprüfen Sie die Dokumentation der modernen PetstoreAPI auf Referenzmuster
Verwenden Sie Apidog, um Ihr API-Design zu validieren
Aktualisieren Sie Ihre OpenAPI-Spezifikation mit Plural-Ressourcennamen

FAQ

Sollte ich meine bestehende API von Singular auf Plural umstellen?

Wenn Ihre API bereits in Produktion ist, ist das Ändern von Ressourcennamen eine Breaking Change. Erwägen Sie:

Hinzufügen neuer v2-Endpunkte mit Pluralnamen
Aufrechterhaltung der Abwärtskompatibilität mit Weiterleitungen
Die Namenskonvention klar dokumentieren

Brechen Sie nicht bestehende Clients nur wegen der Namenskonsistenz.

Was ist mit Ressourcen, die bereits im Plural stehen?

Wenn der Ressourcenname von Natur aus im Plural steht (wie „analytics“ oder „series“), behalten Sie ihn bei:

GET /analytics      ← Bereits im Plural
GET /series         ← Bereits im Plural
GET /species        ← Bereits im Plural

Wie gehe ich mit verschachtelten Ressourcen um?

Halten Sie beide Ebenen im Plural:

GET /users/{userId}/orders              ← Beide im Plural
GET /pets/{petId}/vaccinations          ← Beide im Plural
GET /orders/{orderId}/items             ← Beide im Plural

Was, wenn mein Team Singular bevorzugt?

Konsistenz innerhalb Ihrer API ist am wichtigsten. Wenn Ihr Team bereits Singularnamen standardisiert hat und eine Änderung Verwirrung stiften würde, bleiben Sie beim Singular. Aber für neue APIs verwenden Sie den Plural.

Verwendet GraphQL Plural oder Singular?

GraphQL verwendet typischerweise Singular für Einzelabfragen und Plural für Listen:

query {
  user(id: "123") { ... }      # Singular
  users(limit: 10) { ... }     # Plural
}

Dies unterscheidet sich von REST, da GraphQL-Abfragen explizit angeben, ob ein Element oder mehrere zurückgegeben werden sollen.

Wie geht die moderne PetstoreAPI damit um?

Die moderne PetstoreAPI verwendet durchweg Pluralnamen für alle REST-Endpunkte. Die [REST-API-Anleitung](https://docs.petstoreapi.com/protocols/rest) enthält vollständige Beispiele.

Kann ich Namenskonventionen automatisch testen?

Ja, Apidog kann automatisierte Tests durchführen, um Ressourcennamenmuster über Ihre gesamte API hinweg zu überprüfen. Importieren Sie Ihre OpenAPI-Spezifikation und erstellen Sie Testfälle für Namenskonventionen.

Was ist mit nicht-englischen APIs?

Die Pluralregel gilt unabhängig von der Sprache. Wenn Ihre API französische Ressourcennamen verwendet, verwenden Sie französische Plurale. Wenn sie Japanisch verwendet, folgen Sie den japanischen Grammatikregeln. Das Prinzip (Sammlungen sind im Plural) bleibt dasselbe.