REST API Design: Vermeide Verben in URLs!

TL;DR

REST API URLs sollten Nomen (Ressourcen) enthalten, nicht Verben (Aktionen). HTTP-Methoden (GET, POST, PUT, DELETE) sind die Verben. Die Verwendung von Aktionsverben wie /getUser oder /createOrder verstößt gegen REST-Prinzipien, führt zu Inkonsistenzen und erschwert die Wartung von APIs. Die moderne PetstoreAPI verwendet durchgängig ressourcenorientierte URLs.

Einführung

Sie entwerfen einen API-Endpunkt, um nach Haustieren nach Status zu suchen. Ihr erster Instinkt könnte sein: GET /findPetsByStatus?status=available. Das ist deskriptiv, klar und sagt Ihnen genau, was es tut. Es ist auch falsch.

REST-APIs sollten Nomen in URLs verwenden, nicht Verben. Die HTTP-Methode ist das Verb. GET /pets?status=available ist das korrekte Design. Die URL repräsentiert die Ressource (Haustiere) und die Methode repräsentiert die Aktion (abrufen).

Der alte Swagger Petstore machte diesen Fehler mit Endpunkten wie /pet/findByStatus und /pet/findByTags. Diese Aktionsverben in URLs verstoßen gegen REST-Prinzipien und schaffen Wartungsprobleme. Die moderne PetstoreAPI behebt dies durch die konsequente Verwendung ressourcenorientierter URLs.

In diesem Leitfaden erfahren Sie, warum Verben nicht in REST-URLs gehören, wie Sie ressourcenorientierte Endpunkte entwerfen und wie die moderne PetstoreAPI dies korrekt implementiert.

Das Verb-Problem in REST-APIs

Aktionsverben in URLs zeigen an, dass Sie in RPC-Begriffen (Remote Procedure Call) denken, nicht in REST-Begriffen.

RPC-Stil URLs (Falsch)

POST /createUser
GET /getUser?id=123
PUT /updateUser
DELETE /deleteUser?id=123
GET /findUsersByRole?role=admin
POST /sendEmail
GET /calculateTotal

Diese URLs beschreiben Aktionen. Sie lesen sich wie Funktionsaufrufe: createUser(), getUser(), sendEmail().

REST-Stil URLs (Korrekt)

POST /users
GET /users/123
PUT /users/123
DELETE /users/123
GET /users?role=admin
POST /emails
GET /orders/123/total

Diese URLs beschreiben Ressourcen. Die HTTP-Methode liefert die Aktion.

Warum das wichtig ist

Konsistenz: REST-URLs folgen einem vorhersehbaren Muster. Sobald Sie den Ressourcennamen kennen, kennen Sie alle Endpunkte:

• GET /pets - Haustiere auflisten
• POST /pets - Haustier erstellen
• GET /pets/{id} - Haustier abrufen
• PUT /pets/{id} - Haustier aktualisieren
• DELETE /pets/{id} - Haustier löschen

Bei verb-basierten URLs ist jeder Endpunkt einzigartig. Es gibt kein Muster, dem man folgen könnte.

Skalierbarkeit: Wenn Ihre API wächst, vervielfachen sich verb-basierte URLs:

• /findPetsByStatus
• /findPetsByTags
• /findPetsByOwner
• /findPetsByBreed
• /searchPets
• /queryPets

Ressourcenorientierte URLs verwenden Abfrageparameter:

• GET /pets?status=available
• GET /pets?tags=friendly
• GET /pets?owner=john
• GET /pets?breed=labrador

Ein Endpunkt übernimmt die gesamte Filterung.

Warum HTTP-Methoden die Verben sind

REST nutzt die eingebauten Verben von HTTP. Sie müssen keine eigenen erfinden.

HTTP-Methoden bilden CRUD-Operationen ab

POST   → Erstellen
GET    → Lesen
PUT    → Aktualisieren (ersetzen)
PATCH  → Aktualisieren (teilweise)
DELETE → Löschen

Diese Methoden haben definierte Semantiken. GET ist sicher und idempotent. POST erstellt Ressourcen. DELETE entfernt sie.

Beispiel: Benutzerverwaltung

Falsch (Verben in URLs):

POST /createUser
GET /getUser?id=123
POST /updateUser
POST /deleteUser

Jede Operation verwendet eine andere URL. Die HTTP-Methode vermittelt keine Bedeutung.

Korrekt (HTTP-Methoden als Verben):

POST /users           ← Benutzer erstellen
GET /users/123        ← Benutzer abrufen
PUT /users/123        ← Benutzer aktualisieren
DELETE /users/123     ← Benutzer löschen

Die URL bleibt gleich. Die Methode ändert sich.

Vorteile der Verwendung von HTTP-Methoden

1. Caching: GET-Anfragen können gecacht werden. Browser und Proxies wissen das. Wenn Sie POST /getUser verwenden, funktioniert das Caching nicht.

2. Idempotenz: PUT und DELETE sind idempotent. Das mehrmalige Aufrufen hat denselben Effekt wie das einmalige Aufrufen. Dies ist wichtig für die Wiederholungslogik.

3. Sicherheit: GET ist sicher – es ändert keinen Zustand. Tools und Crawler können GET-Endpunkte sicher aufrufen.

4. Standardkonformität: HTTP-Clients, Proxies und Caches verstehen HTTP-Methoden. Sie verstehen Ihre benutzerdefinierten Verben nicht.

Beispiele aus dem realen Swagger Petstore

Der alte Swagger Petstore enthält mehrere verb-basierte Endpunkte.

Beispiel 1: Haustiere nach Status finden

Swagger Petstore (Falsch):

GET /pet/findByStatus?status=available

Probleme:

• findByStatus ist eine Verbphrase
• Inkonsistent mit dem /pet/{id}-Endpunkt
• Kann nicht einfach erweitert werden (was ist mit dem Finden nach anderen Kriterien?)

Moderne PetstoreAPI (Korrekt):

GET /pets?status=AVAILABLE

Vorteile:

• Ressourcenorientiert (/pets)
• Verwendet Abfrageparameter zur Filterung
• Konsistent mit anderen Endpunkten
• Leicht erweiterbar: GET /pets?status=AVAILABLE&species=dog

Die vollständige Implementierung finden Sie in der REST-Dokumentation der modernen PetstoreAPI.

Beispiel 2: Haustiere nach Tags finden

Swagger Petstore (Falsch):

GET /pet/findByTags?tags=tag1,tag2

Moderne PetstoreAPI (Korrekt):

GET /pets?tags=friendly,trained

Beispiel 3: Benutzeranmeldung

Swagger Petstore (Falsch):

GET /user/login?username=john&password=secret

Mehrere Probleme:

• login ist ein Verb
• Verwendung von GET zur Authentifizierung (Sicherheitskatastrophe)
• Passwörter in URL-Abfrageparametern

Moderne PetstoreAPI (Korrekt):

POST /auth/login
Content-Type: application/json

{
  "username": "john",
  "password": "secret123"
}

Vorteile:

• Ressourcenorientiert (/auth)
• Korrekte HTTP-Methode (POST)
• Anmeldeinformationen im Anfragetext, nicht in der URL
• Gibt JWT-Token für nachfolgende Anfragen zurück

Wie die moderne PetstoreAPI dies behebt

Die moderne PetstoreAPI verwendet durchgängig ressourcenorientierte URLs.

Haustierverwaltung

GET /pets                    ← Alle Haustiere auflisten
GET /pets?status=AVAILABLE   ← Nach Status filtern
GET /pets?species=dog        ← Nach Spezies filtern
GET /pets/{id}               ← Spezifisches Haustier abrufen
POST /pets                   ← Neues Haustier erstellen
PUT /pets/{id}               ← Haustier aktualisieren
PATCH /pets/{id}             ← Teilweise Aktualisierung
DELETE /pets/{id}            ← Haustier löschen

Keine Verben. Nur Ressourcen und HTTP-Methoden.

Auftragsverwaltung

GET /orders                  ← Aufträge auflisten
GET /orders/{id}             ← Auftrag abrufen
POST /orders                 ← Auftrag erstellen
PUT /orders/{id}             ← Auftrag aktualisieren
DELETE /orders/{id}          ← Auftrag stornieren
GET /orders/{id}/items       ← Auftragsartikel abrufen

Komplexe Operationen

Für Operationen, die nicht sauber auf CRUD abgebildet werden können, verwendet die moderne PetstoreAPI Sub-Ressourcen:

POST /orders/{id}/payment    ← Zahlung für Bestellung verarbeiten
POST /orders/{id}/shipment   ← Sendung für Bestellung erstellen
POST /pets/{id}/adoption     ← Adoptionsprozess starten

Diese sind immer noch ressourcenorientiert. /orders/{id}/payment repräsentiert die Zahlungsressource für einen Auftrag.

Wenn Verben notwendig erscheinen

Einige Operationen passen nicht zum CRUD-Modell. Hier erfahren Sie, wie Sie sie ohne Verben in URLs handhaben können.

Suchoperationen

Falsch:

GET /searchPets?query=labrador

Korrekte Option 1 (Abfrageparameter):

GET /pets?search=labrador

Korrekte Option 2 (Suchressource):

GET /pets/search?q=labrador

Korrekte Option 3 (QUERY-Methode):

QUERY /pets
Content-Type: application/json

{
  "query": "labrador",
  "filters": {
    "status": "AVAILABLE"
  }
}

Die moderne PetstoreAPI unterstützt alle drei Muster je nach Komplexität.

Berechnungen

Falsch:

GET /calculateShipping?weight=10&destination=NY

Korrekt:

GET /shipping-estimates?weight=10&destination=NY

Die Ressource ist „Versandkosten-Schätzungen“, nicht die Berechnungsaktion.

Batch-Operationen

Falsch:

POST /batchDeletePets

Korrekt:

DELETE /pets?ids=1,2,3

Oder verwenden Sie eine Batch-Ressource:

POST /pets/batch-operations
Content-Type: application/json

{
  "operation": "delete",
  "ids": [1, 2, 3]
}

Aktionen, die den Zustand ändern

Falsch:

POST /activateUser
POST /deactivateUser

Korrekt:

PATCH /users/{id}
Content-Type: application/json

{
  "status": "ACTIVE"
}

Zustandsänderungen sind Aktualisierungen der Ressource.

URL-Design mit Apidog testen

Apidog hilft Ihnen, das REST-API-Design zu validieren und die Verwendung von Verben in URLs zu erkennen.

Moderne PetstoreAPI importieren

1. Importieren Sie die OpenAPI-Spezifikation der modernen PetstoreAPI
2. Apidog generiert automatisch Testfälle
3. Überprüfen Sie die Endpunktstruktur und -benennung

Auf Verben in URLs prüfen

Erstellen Sie eine benutzerdefinierte Validierungsregel in Apidog:

// Prüfen, ob die URL gängige Aktionsverben enthält
const verbs = ['get', 'create', 'update', 'delete', 'find', 'search',
               'calculate', 'process', 'send', 'fetch'];
const url = request.url.toLowerCase();

for (const verb of verbs) {
  if (url.includes(`/${verb}`)) {
    throw new Error(`URL enthält Verb: ${verb}. Verwenden Sie stattdessen ressourcenorientierte URLs.`);
  }
}

Endpunktkonsistenz testen

Apidog kann überprüfen, ob verwandte Endpunkte konsistenten Mustern folgen:

✓ GET /pets
✓ POST /pets
✓ GET /pets/{id}
✓ PUT /pets/{id}
✓ DELETE /pets/{id}

Alle verwenden dieselbe Basisressource (/pets).

Mit der modernen PetstoreAPI vergleichen

1. Importieren Sie sowohl Ihre API als auch die moderne PetstoreAPI in Apidog
2. Vergleichen Sie die Endpunktstrukturen nebeneinander
3. Inkonsistenzen und Verb-Verwendung identifizieren
4. Refaktorieren Sie Ihre API, um den REST-Prinzipien zu entsprechen

Migrationsstrategien

Wenn Sie eine bestehende API mit Verben in URLs haben, erfahren Sie hier, wie Sie migrieren.

Strategie 1: Versionierung

Erstellen Sie eine neue API-Version mit korrekten URLs:

# Alte API (v1)
GET /api/v1/findPetsByStatus?status=available

# Neue API (v2)
GET /api/v2/pets?status=available

Pflegen Sie v1 für die Abwärtskompatibilität, fördern Sie die Migration zu v2.

Strategie 2: Aliasing

Unterstützen Sie vorübergehend alte und neue URLs:

# Alte URL (veraltet)
GET /pet/findByStatus?status=available

# Neue URL (bevorzugt)
GET /pets?status=available

Geben Sie Deprecation-Warnungen in Antworten zurück:

{
  "data": [...],
  "warnings": [
    {
      "code": "DEPRECATED_ENDPOINT",
      "message": "Dieser Endpunkt ist veraltet. Verwenden Sie stattdessen GET /pets?status=available.",
      "sunset": "2027-01-01"
    }
  ]
}

Strategie 3: Weiterleitungen

Verwenden Sie HTTP 301-Weiterleitungen für einfache Migrationen:

GET /pet/findByStatus?status=available
→ 301 Moved Permanently
Location: /pets?status=available

Dies funktioniert für GET-Anfragen, aber nicht für POST, PUT oder DELETE.

Fazit

REST API URLs sollten Nomen (Ressourcen) enthalten, nicht Verben (Aktionen). HTTP-Methoden liefern die Verben. Dieses Prinzip schafft konsistente, skalierbare und wartbare APIs.

Der alte Swagger Petstore verstieß dagegen mit Endpunkten wie /pet/findByStatus. Die moderne PetstoreAPI behebt dies durch die durchgängige Verwendung ressourcenorientierter URLs: /pets?status=AVAILABLE.

Wichtige Erkenntnisse:

• Verwenden Sie Nomen in URLs: /pets, /orders, /users
• Lassen Sie HTTP-Methoden die Verben sein: GET, POST, PUT, DELETE
• Verwenden Sie Abfrageparameter zur Filterung: /pets?status=available
• Für komplexe Operationen verwenden Sie Sub-Ressourcen: /orders/{id}/payment
• Testen Sie Ihr API-Design mit Apidog, um die Verwendung von Verben frühzeitig zu erkennen

In der Dokumentation der modernen PetstoreAPI finden Sie vollständige Beispiele für ressourcenorientiertes URL-Design.

FAQ

Kann ich jemals Verben in REST-URLs verwenden?

Selten. Wenn eine Operation wirklich nicht zum Ressourcenmodell passt (wie /search oder /login), könnte ein Verb akzeptabel sein. Aber in 95 % der Fälle können Sie es als Ressource modellieren.

Was ist mit /login und /logout?

Dies sind häufige Ausnahmen. Viele APIs verwenden /auth/login und /auth/logout. Alternativ können Sie sie als Ressourcen modellieren: POST /sessions (Anmeldung) und DELETE /sessions/{id} (Abmeldung).

Wie gehe ich mit komplexen Abfragen um?

Verwenden Sie Abfrageparameter für einfache Filterung: /pets?status=available&species=dog. Für komplexe Abfragen verwenden Sie die HTTP-Methode QUERY oder eine Suchressource: POST /pets/search.

Was, wenn meine Operation nicht auf CRUD abbildbar ist?

Modellieren Sie es als Sub-Ressource. Anstatt POST /processPayment verwenden Sie POST /orders/{id}/payment. Die Zahlung ist eine Ressource, die mit dem Auftrag zusammenhängt.

Wie teste ich, ob meine URLs ressourcenorientiert sind?

Verwenden Sie Apidog, um Ihre OpenAPI-Spezifikation zu importieren und auf Verben in URLs zu prüfen. Vergleichen Sie Ihre API-Struktur mit der modernen PetstoreAPI als Referenz.

Sollte ich /pets/search oder /pets?search=query verwenden?

Beide sind akzeptabel. /pets?search=query ist einfacher für die grundlegende Suche. /pets/search oder QUERY /pets funktioniert besser für komplexe Suchen mit mehreren Parametern.

Wie migriere ich von verb-basierten URLs?

Verwenden Sie API-Versionierung (/v2/pets anstelle von /v1/findPets), fügen Sie Deprecation-Warnungen hinzu und geben Sie den Clients Zeit zur Migration. Einzelheiten finden Sie im Abschnitt Migrationsstrategien.

Verwendet die moderne PetstoreAPI Verben in URLs?

Die moderne PetstoreAPI vermeidet Verben in URLs. Operationen wie Suchen, Filtern und Authentifizierung werden als Ressourcen modelliert oder verwenden Abfrageparameter. Beispiele finden Sie in der REST-API-Dokumentation.