Zum Hauptinhalt springen

URL-Design

Eine durchdachte URL-Struktur ist entscheidend für eine benutzerfreundliche REST-API. Sie sollte klar, konsistent und intuitiv sein, damit Nutzer und Entwickler leicht verstehen, wie die API funktioniert. Hier sind die wichtigsten Best Practices für ein effizientes URL-Design und Ressourcenstruktur:

1. Verwendung von Substantiven und Pluralformen für Ressourcen​

  • URLs repräsentieren Ressourcen und sollten daher Substantive statt Verben verwenden.
  • Nutze immer die Pluralform, um Sammlungen von Ressourcen darzustellen, auch wenn eine spezifische Ressource aufgerufen wird.

Beispiel:

  • Korrekt: /users, /products, /orders
  • Nicht empfohlen: /getUsers, /createOrder, /deleteProduct

2. Eindeutige Ressourcen mit IDs​

  • Um auf eine spezifische Ressource zuzugreifen, verwende eindeutige, unveränderliche IDs (z. B. Datenbank-IDs oder UUIDs).

Beispiel:

  • /products/789: Greift auf das Produkt mit der ID 789 zu.

3. Filterung, Sortierung und Paginierung mit Query-Parametern​

  • Nutze Query-Parameter für Filter, Sortierung und Paginierung, statt diese Informationen in die URL zu integrieren.
  • Gängige Parameter sind sort, page, limit sowie spezifische Filteroptionen.

Beispiel:

  • Filterung: /products?category=electronics
  • Sortierung: /products?sort=price
  • Pagination: /products?page=2&limit=20

4. API-Versionierung in der URL​

  • Versioniere die API, um Änderungen vorzunehmen, ohne bestehende Integrationen zu beeinflussen.
  • Die Versionierung kann in der URL (/v1/) oder im Header erfolgen, häufig wird die URL-Versionierung verwendet.

Beispiel:

  • Version 1: /v1/products
  • Version 2: /v2/products

5. Verzicht auf Dateiendungen​

  • Verzichte auf Dateiendungen wie .json oder .xml in URLs. Der Client kann das Format über den Accept-Header anfordern.

Beispiel:

  • Korrekt: /products
  • Nicht empfohlen: /products.json