DEV Community

Cover image for REST API Namenskonventionen: Ein praktischer Leitfaden
Emre Demir
Emre Demir

Posted on Originally published at apidog.com

REST API Namenskonventionen: Ein praktischer Leitfaden

REST-API-Benennung: 10 Regeln für konsistente Endpunkte

Öffnen Sie einen beliebigen Codebestand, der älter als zwei Jahre ist, und Sie werden die Narben finden: /getUser, /user_list, `[REDACTED PATH]

{% cta https://apidog.com/?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation %} Apidog heute testen {% endcta %}

Die Benennung ist die günstigste API-Designentscheidung und zugleich die teuerste, die man später ändern kann. Sobald Clients von /getOrders abhängig sind, müssen Sie diesen Endpunkt unter Umständen jahrelang unterstützen.

Dieser Leitfaden liefert eine konkrete Regel für jede wichtige Benennungsentscheidung in einer REST-API – jeweils mit einem guten und einem schlechten Beispiel. Er ergänzt unsere REST-API-Richtlinien für Entwickler und konzentriert sich auf den Bereich, über den Teams am häufigsten diskutieren: Namen.

1. Verwenden Sie Pluralnomen für Sammlungen

Eine URL benennt eine Ressource, keine Operation. Sammlungen sind Mengen von Objekten und sollten deshalb im Plural stehen.

Richtig:

http
GET /v1/products
GET /v1/products/89
GET /v1/orders

Falsch:

http
GET /v1/getProducts
GET /v1/product
GET /v1/productList

/products bezeichnet die Sammlung von Produkten, /products/89 ein bestimmtes Element innerhalb dieser Sammlung. Die Pluralform funktioniert auf beiden Ebenen natürlich.

Auch die Microsoft REST API-Richtlinien empfehlen Pluralnomen. Öffentliche APIs wie Stripe, GitHub und Shopify folgen demselben Muster.

Ausnahme: Singleton-Ressourcen. Wenn ein Benutzer genau einen Warenkorb besitzt, ist `[REDACTED PATH]

2. Vermeiden Sie Verben in Pfaden

Die HTTP-Methode ist bereits das Verb. Ein zusätzliches Verb im Pfad dupliziert Informationen und bricht das Ressourcenmodell.

Richtig:

GET    /v1/orders/42
DELETE /v1/orders/42
PATCH  /v1/orders/42
Enter fullscreen mode Exit fullscreen mode

Falsch:

GET  /v1/fetchOrder/42
POST /v1/deleteOrder/42
POST /v1/updateOrderStatus
Enter fullscreen mode Exit fullscreen mode

Verben-basierte Pfade erhöhen außerdem den Wartungsaufwand. Eine Ressource mit vier HTTP-Methoden wird zu vier separat zu dokumentierenden, testenden und cachenden Endpunkten.

Auch die Cache-Invalidierung wird schwieriger. Ein CDN kann GET /v1/orders/42 cachen und dieselbe URL bei DELETE /v1/orders/42 invalidieren. Es kann jedoch nicht automatisch erkennen, dass /fetchOrder/42 und /deleteOrder/42 dieselbe Ressource betreffen.

3. Verwenden Sie Kebab-Case in URL-Pfaden

Mehrteilige Pfadsegmente sollten Bindestriche als Trennzeichen verwenden.

Richtig:

/v1/gift-cards
/v1/shipping-addresses
Enter fullscreen mode Exit fullscreen mode

Falsch:

/v1/giftCards
/v1/gift_cards
/v1/GiftCards
Enter fullscreen mode Exit fullscreen mode

Kebab-Case hat drei praktische Vorteile:

  • Google behandelt Bindestriche als Worttrenner, wodurch öffentliche API-Dokumentation besser indexiert werden kann.
  • Unterstriche können verschwinden, wenn eine URL unterstrichen dargestellt wird.
  • CamelCase begünstigt Groß-/Kleinschreibungsfehler: /giftCards und /giftcards sind auf vielen Servern unterschiedliche URLs.

Die Zalando RESTful API-Richtlinien machen Kebab-Case zu einer MUSS-Regel.

4. Wählen Sie eine JSON-Groß-/Kleinschreibung

Für JSON-Feldnamen funktionieren sowohl camelCase als auch snake_case. Problematisch ist nur eine Mischung.

Richtig – camelCase:

{
  "orderId": 42,
  "createdAt": "2026-08-30T09:15:00Z",
  "totalAmount": 4999
}
Enter fullscreen mode Exit fullscreen mode

Richtig – snake_case:

{
  "order_id": 42,
  "created_at": "2026-08-30T09:15:00Z",
  "total_amount": 4999
}
Enter fullscreen mode Exit fullscreen mode

Falsch:

{
  "orderId": 42,
  "created_at": "2026-08-30T09:15:00Z",
  "TotalAmount": 4999
}
Enter fullscreen mode Exit fullscreen mode

camelCase passt gut zu JavaScript- und Java-Clients. snake_case ist leicht zu scannen und passt zu Ruby, Python und vielen SQL-Spaltennamen; Stripe verwendet es durchgängig.

Treffen Sie die Entscheidung anhand Ihrer wichtigsten API-Konsumenten, dokumentieren Sie sie im Styleguide und überprüfen Sie sie automatisch anhand Ihrer Schemas. Gemischte Schreibweisen sind kein Geschmacksproblem, sondern ein Governance-Versagen.

5. Begrenzen Sie die Verschachtelung auf zwei Ebenen

Verschachtelung kann Besitz ausdrücken:

GET /v1[REDACTED PATH]
Enter fullscreen mode Exit fullscreen mode

Das bedeutet: Bestellungen, die Benutzer 42 gehören. Nach zwei Ebenen wird der Pfad jedoch meist unnötig kompliziert.

Richtig:

GET /v1[REDACTED PATH]
GET /v1/orders/1337/refunds
Enter fullscreen mode Exit fullscreen mode

Falsch:

GET /v1[REDACTED PATH]
Enter fullscreen mode Exit fullscreen mode

Tiefe Verschachtelung zwingt Clients, jede übergeordnete ID mitzuschicken, selbst wenn die untergeordnete Ressource eine global eindeutige ID besitzt.

Ein einfacher Geruchstest: Enthält eine URL drei oder mehr IDs, sollten Sie sie wahrscheinlich abflachen. Eine Rückerstattung kann über /orders/1337/refunds/7 erreichbar sein; eine Bestellung sollte nach ihrer Erstellung auch unter /orders/1337 selbstständig adressierbar sein.

6. Platzieren Sie Filter, Sortierung und Paginierung in Query-Parametern

Pfade identifizieren Ressourcen. Query-Parameter steuern, wie diese Ressourcen angezeigt oder gefiltert werden.

Richtig:

GET /v1/orders?status=active&sort=-created_at&limit=50&cursor=eyJpZCI6NDJ9
GET /v1/products?category=electronics&min_price=1000
Enter fullscreen mode Exit fullscreen mode

Falsch:

GET /v1/orders/active
GET /v1/orders/sorted-by-date-desc
GET /v1/getOrdersByStatusAndDate
Enter fullscreen mode Exit fullscreen mode

Das Muster sort=-created_at nutzt ein Minuspräfix für absteigende Sortierung. Es stammt aus der JSON:API-Spezifikation und macht einen zusätzlichen Parameter wie order=desc überflüssig.

Filterpfade wie /orders/active wirken zunächst einfach. Sobald Filter kombiniert werden, entstehen jedoch immer neue Endpunkte. Entscheiden Sie sich auch bei der Paginierung einmal für ein Schema – etwa limit/cursor oder page/per_page – und verwenden Sie es für alle Sammlungen. Der API-Paginierungsleitfaden erläutert die Vor- und Nachteile von Cursor- und Offset-Paginierung.

7. Verwenden Sie eine Hauptversion im Pfad

Übliche Varianten sind:

/v1/products
Enter fullscreen mode Exit fullscreen mode

oder eine Header-Versionierung:

Accept: application/vnd.myapi.v1+json
Enter fullscreen mode Exit fullscreen mode

Header-Versionierung ist aus REST-Sicht „reiner“, weil dieselbe URL über mehrere Versionen hinweg dieselbe Ressource bezeichnet. Die Google API-Designanleitung beschreibt beide Ansätze als etablierte Optionen.

In der Praxis ist die Pfad-Versionierung oft robuster:

  • Sie ist in jeder Protokollzeile sichtbar.
  • Sie kann ohne zusätzliche Vary-Logik gecacht werden.
  • Sie lässt sich direkt im Browser oder mit curl testen.
  • Clients können den Versionsheader nicht versehentlich vergessen.

Verwenden Sie eine Hauptversion wie /v1/, nicht /v1.2/. Kleinere Änderungen sollten additiv und nicht brechend sein. Weitere Entscheidungskriterien finden Sie im Vergleich der API-Versionierungsstrategien.

8. Behandeln Sie Ressourcen-IDs als undurchsichtig

Sequenzielle IDs wie /orders/41, /orders/42 und /orders/43 verraten Informationen über Ihr System und erleichtern Enumerationsangriffe. Angreifer können den ID-Raum durchsuchen und dabei Autorisierungslücken finden.

Gebrochene objektbasierte Autorisierung – heute als Broken Object Level Authorization bezeichnet – steht auf Platz eins der OWASP API Security Top 10.

Richtig:

GET /v1/orders/ord_9f8e2a71b3
GET /v1[REDACTED PATH]
Enter fullscreen mode Exit fullscreen mode

Falsch, wenn Enumeration relevant ist:

GET /v1/orders/42
GET /v1/invoices/10883
Enter fullscreen mode Exit fullscreen mode

Präfixierte zufällige IDs wie ord_9f8e2a71b3 sind in vielen Fällen ein gutes Muster: Sie sind schwer zu erraten, in Logs verständlich und sicherer offenzulegen.

Wichtig: Autorisierungsprüfungen bleiben zwingend erforderlich. Undurchsichtige IDs begrenzen den Schaden einer fehlenden Prüfung, ersetzen sie aber nicht. Intern können Sie weiterhin numerische Primärschlüssel verwenden; die Regel betrifft die IDs in öffentlichen URLs.

9. Modellieren Sie Nicht-CRUD-Aktionen als Controller-Ressourcen

Nicht jede Operation passt sauber in CRUD. Beispiele sind das Stornieren einer Bestellung, das erneute Ausführen einer Zahlung oder das erneute Versenden einer E-Mail.

Richtig:

POST /v1/orders/42/cancel
POST /v1/payments/pay_88a1/retry
Enter fullscreen mode Exit fullscreen mode

Falsch:

PATCH /v1/orders/42
{ "status": "cancelled" }

POST /v1/cancelOrder
{ "orderId": 42 }
Enter fullscreen mode Exit fullscreen mode

Das Controller-Muster ist die wichtigste Ausnahme von der Regel „keine Verben in Pfaden“: Das Verb steht am Ende des Pfades und liegt unterhalb der Ressource, auf die es wirkt.

Eine Stornierung ist oft mehr als eine Feldänderung. Sie kann Rückerstattungen auslösen, Lagerbestände freigeben und Benachrichtigungen versenden. Ein eigener /cancel-Endpunkt macht die Absicht eindeutig, ermöglicht separate Berechtigungen und Audit-Logs und lässt aktionsspezifische Eingaben wie einen Stornierungsgrund zu.

10. Halten Sie Header und Query-Parameter konsistent

Benutzerdefinierte Header sollten die HTTP-Konvention übernehmen:

Idempotency-Key: abc123
[REDACTED IDENTIFIER]
Enter fullscreen mode Exit fullscreen mode

Vermeiden Sie das alte X--Präfix; es wurde 2012 durch RFC 6648 obsolet. Headernamen sind auf Protokollebene nicht groß-/kleinschreibungssensitiv. Dokumentation und SDKs sollten sie trotzdem einheitlich darstellen.

Query-Parameter sollten der Schreibweise Ihrer JSON-Felder folgen. Bei snake_case:

?vmin_price=1000&created_after=2026-01-01
Enter fullscreen mode Exit fullscreen mode

Korrekt ohne Tippfehler:

?min_price=1000&created_after=2026-01-01
Enter fullscreen mode Exit fullscreen mode

Nicht:

?minPrice=1000
Enter fullscreen mode Exit fullscreen mode

Wer created_at in einer Antwort sieht und createdAfter als Query-Parameter verwenden muss, wird die API beim ersten Versuch wahrscheinlich falsch bedienen.

Das vollständige Regelwerk

Nr. Regel Richtig Falsch
1 Pluralnomen für Sammlungen /products, /products/89 /getProducts, /productList
2 Keine Verben in Pfaden DELETE /orders/42 POST /deleteOrder/42
3 Kebab-Case für Pfadsegmente /gift-cards /giftCards, /gift_cards
4 Eine dokumentierte JSON-Schreibweise order_id überall orderId und order_id gemischt
5 Maximal zwei Verschachtelungsebenen /orders/1337/refunds `[REDACTED PATH]
6 Filter und Paginierung in Query-Parametern ?status=active&sort=-created_at /orders/active
7 Hauptversion im Pfad /v1/products /v1.2/products, Versionsheader
8 Undurchsichtige Ressourcen-IDs /orders/ord_9f8e2a71b3 /orders/42
9 Controller-Muster für Aktionen POST /orders/42/cancel PATCH mit {"status":"cancelled"}
10 Konsistente Schreibweise für Header und Parameter Idempotency-Key, ?min_price= X-IDEMPOTENCY_KEY, ?minPrice=

Konventionen im großen Maßstab durchsetzen

Ein Styleguide im Wiki reicht nicht aus. Konsistente APIs entstehen, wenn Teams Konventionen festlegen und überprüfen, bevor Code geschrieben wird. Das ist der Kern funktionierender API-Governance.

Hier kann Apidog in den Workflow passen:

  • Definieren Sie Endpunkte in einem schema-first-Designer.
  • Machen Sie Pfade, Schreibweisen und Parameternamen zu expliziten Design-Artefakten.
  • Definieren Sie Pagination-, Error- und Money-Schemas einmal und verwenden Sie sie wieder.
  • Prüfen Sie Namen wie /getUserOrders, bevor Clients davon abhängig werden.
  • Leiten Sie Dokumentation, Mock-Server und Tests aus der Spezifikation ab.

So werden genehmigte Namen zu den Namen, die tatsächlich ausgeliefert werden. Laden Sie Apidog herunter und testen Sie es kostenlos mit Ihrem nächsten Endpunkt. Eine bestehende API nachzurüsten ist schwierig – bei neuen Endpunkten die Linie zu halten, ist es nicht.

Häufig gestellte Fragen

Sollten REST-URLs Plural oder Singular sein?

Plural – für jede Ressource mit mehr als einer Instanz:

http
/products
/orders
/users

Die Pluralform bleibt für die Sammlung (/orders) und ein einzelnes Mitglied (/orders/42) natürlich. Verwenden Sie Singularnamen nur für echte Singletons wie `[REDACTED PATH]-API ist](https://apidog.com/de/blog/what-is-rest-api?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation), erklärt die Grundlagen der Ressourcenmodellierung.

Ist camelCase oder snake_case besser für JSON-Feldnamen?

Keine Variante ist grundsätzlich überlegen. camelCase passt gut zu JavaScript-lastigen Konsumenten; snake_case ist gut lesbar und passt zu Python, Ruby und Stripes öffentlicher API.

Die wichtigste Regel lautet: Wählen Sie eine Schreibweise, dokumentieren Sie sie und setzen Sie sie über Schemaüberprüfung durch. Eine gemischte Schreibweise über verschiedene Endpunkte hinweg schadet mehr als die konkrete Wahl.

Sollte die API-Version in die URL oder in einen Header?

Verwenden Sie den Pfad (/v1/orders), sofern keine starke Hypermedia-Anforderung dagegenspricht. Pfadversionen sind in Logs, Caches und Browser-Tests sichtbar und können nicht durch einen vergessenen Header ausfallen.

Verwenden Sie nur Hauptversionen. Kleinere Änderungen sollten additiv und nicht brechend ausgeliefert werden.

Sind Verben jemals in einem REST-API-Pfad akzeptabel?

Ja: bei Controller-Endpunkten für Nicht-CRUD-Aktionen, zum Beispiel:

POST /orders/42/cancel
POST /payments/pay_88a1/retry
Enter fullscreen mode Exit fullscreen mode

Das Verb steht am Ende des Pfades und innerhalb der betroffenen Ressource. Die Methode ist POST. In allen anderen Fällen trägt die HTTP-Methode das Verb, während der Pfad aus Nomen besteht.

Weiterführende Links

Top comments (0)