Blog

Schlechtes REST API Design: Warum Swagger Petstore ein schlechtes Beispiel ist

Ashley Innocent

Ashley Innocent

13 March 2026

Schlechtes REST API Design: Warum Swagger Petstore ein schlechtes Beispiel ist

Apidog für Unternehmen

On-Premises-Bereitstellung

SSO & RBAC

SOC 2 konform

Apidog Enterprise entdecken

Kurz gesagt

Der Swagger Petstore verstößt gegen grundlegende REST-Prinzipien: Er verwendet inkonsistent singuläre Ressourcennamen, fügt Aktionsverben in URLs ein, gibt falsche HTTP-Statuscodes zurück, offenbart Passwörter in GET-Anfragen und liefert nackte Arrays ohne Metadaten. Modern PetstoreAPI behebt all diese Probleme mit einem korrekten RESTful-Design, RFC 9457-Fehlerbehandlung und produktionsreifen Mustern.

Einleitung

Seit über einem Jahrzehnt ist der Swagger Petstore das Standardbeispiel zum Erlernen von OpenAPI. Millionen von Entwicklern haben ihn studiert, seine Muster kopiert und darauf basierend produktive APIs erstellt. Es gibt nur ein Problem: Er lehrt Sie, schlechte APIs zu bauen.

Der Swagger Petstore verstößt gegen grundlegende REST-Prinzipien, enthält Sicherheitslücken und demonstriert Anti-Muster, die Produktionssystemen schaden. Es ist, als würde man Autofahren mit einem Auto lernen, bei dem Brems- und Gaspedal vertauscht sind – man lernt, aber man lernt es falsch.

Der Schaden ist real. Entwickler, die vom Swagger Petstore gelernt haben, übernehmen diese Anti-Muster in den Produktionscode. APIs werden mit inkonsistenter Benennung, falschen HTTP-Methoden und Sicherheitslücken gebaut. Code-Reviews übersehen diese Probleme, weil „Petstore es ja auch so macht.“

💡
Wenn Sie REST-APIs entwickeln oder testen, hilft Ihnen Apidog, das API-Design anhand von REST-Prinzipien zu validieren, das Endpunktverhalten zu testen und Designfehler zu erkennen, bevor sie in Produktion gehen. Sie können OpenAPI-Spezifikationen importieren, automatisierte Tests ausführen und sicherstellen, dass Ihre API die korrekten REST-Konventionen befolgt.
Schaltfläche

In diesem Leitfaden erfahren Sie genau, was am Swagger Petstore falsch ist, warum diese Probleme wichtig sind und wie die Modern PetstoreAPI sie mit produktionsreifen Mustern behebt. Sie sehen Vergleiche nebeneinander, verstehen die Auswirkungen jedes Verstoßes und entdecken, wie Sie Ihre APIs mit Apidog richtig testen.

Das Vermächtnisproblem des Swagger Petstore

Der Swagger Petstore wurde 2011 als einfaches Beispiel für die Swagger-Spezifikation (jetzt OpenAPI) erstellt. Er erfüllte seinen Zweck: zu demonstrieren, wie eine OpenAPI-Spezifikation geschrieben wird. Er war jedoch nie als Referenz für das REST-API-Design gedacht.

Warum er zum De-facto-Standard wurde

Wenn Entwickler OpenAPI lernen, beginnen sie mit dem offiziellen Beispiel. Der Swagger Petstore ist dieses Beispiel. Er findet sich in der Dokumentation, in Tutorials und in Code-Generatoren. Wenn Sie Swagger UI oder Swagger Codegen verwendet haben, haben Sie ihn gesehen.

Das Problem: Entwickler gehen davon aus, dass „offizielles Beispiel = Best Practice“ bedeutet. Sie kopieren die Muster, ohne sie zu hinterfragen. API-Designkurse verwenden ihn als Lehrmittel. Unternehmen bauen interne APIs nach seiner Struktur.

Die Kosten schlechter Beispiele

Schlechte Beispiele summieren sich im Laufe der Zeit:

  1. Junior-Entwickler lernen Anti-Muster - Sie wissen nicht, dass es Fehler sind
  2. Code-Generatoren perpetuieren die Probleme - Generierte SDKs erben die Fehler
  3. Dokumentationstools zeigen schlechte Beispiele - Swagger UI zeigt den Petstore standardmäßig an
  4. Unternehmen bauen Produktions-APIs auf diese Weise - „Wenn es für Swagger gut genug ist…“

Der Swagger Petstore hat wahrscheinlich mehr API-Designs beeinflusst als jedes andere Beispiel in der Geschichte. Deshalb sind seine Mängel von Bedeutung.

Kritische REST-Verletzungen im Swagger Petstore

Lassen Sie uns die spezifischen REST-Verstöße im Swagger Petstore untersuchen und warum sie falsch sind.

1. Inkonsistente Ressourcennamen (Plural vs. Singular)

Der Verstoß:

GET /pet/{petId}           ← Singular
GET /store/inventory       ← Plural
POST /pet                  ← Singular
GET /user/{username}       ← Singular

Warum es falsch ist:

REST-Ressourcen stellen Sammlungen dar. Eine Sammlung ist Plural. Wenn Sie auf /pets zugreifen, greifen Sie auf die Haustiersammlung zu. Wenn Sie auf /pets/123 zugreifen, greifen Sie auf Element 123 in der Haustiersammlung zu.

Das Mischen von Singular und Plural bricht dieses mentale Modell. Greift /pet/123 auf die Haustiersammlung oder eine einzelne Haustierressource zu? Die Inkonsistenz führt zu Verwirrung.

Die Lösung von Modern PetstoreAPI:

GET /pets/{petId}          ← Immer Plural
GET /stores/inventory      ← Konsistent
POST /pets                 ← Plural für Sammlung
GET /users/{username}      ← Überall Plural

Modern PetstoreAPI verwendet konsistent Plural-Ressourcennamen über alle Endpunkte hinweg. Prüfen Sie die REST-API-Dokumentation für die vollständige Endpunktstruktur.

2. Aktionsverben in URLs

Der Verstoß:

GET /pet/findByStatus?status=available
GET /pet/findByTags?tags=tag1,tag2
GET /user/login?username=john&password=secret
GET /user/logout

Warum es falsch ist:

REST-URLs sollten Ressourcen (Substantive), nicht Aktionen (Verben) darstellen. Die HTTP-Methode ist das Verb. GET /pets bedeutet „hole die Haustierressource“. Das Hinzufügen von findByStatus ist redundant – dafür sind Abfrageparameter da.

Aktionsverben in URLs deuten darauf hin, dass Sie in RPC-Begriffen (Remote Procedure Call) denken, nicht in REST-Begriffen. Sie legen Implementierungsdetails offen, anstatt Ressourcen zu nutzen.

Die Lösung von Modern PetstoreAPI:

GET /pets?status=AVAILABLE              ← Ressource + Filter
GET /pets?tags=tag1,tag2                ← Abfrageparameter zum Filtern
POST /auth/login                        ← Separate Authentifizierungsressource
POST /auth/logout                       ← RESTful Authentifizierungs-Endpunkte

Die Modern PetstoreAPI verwendet Abfrageparameter zum Filtern und separate Authentifizierungsressourcen. Siehe den Authentifizierungsleitfaden für korrekte Authentifizierungsmuster.

3. Falsche HTTP-Statuscodes

Der Verstoß:

POST /pet
Response: 200 OK          ← Sollte 201 Created sein

DELETE /pet/{petId}
Response: 200 OK          ← Sollte 204 No Content sein
{
  "message": "Pet deleted"
}

Warum es falsch ist:

HTTP-Statuscodes haben spezifische Bedeutungen:

Die Verwendung von 200 für alles bricht die HTTP-Semantik. Clients können nicht zwischen „Ressource abgerufen“ und „Ressource erstellt“ unterscheiden. Die Rückgabe eines Bodys bei DELETE verschwendet Bandbreite – der Client benötigt keine Bestätigungstext.

Die Lösung von Modern PetstoreAPI:

POST /pets
Response: 201 Created
Location: /pets/019b4132-70aa-764f-b315-e2803d882a24
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "status": "AVAILABLE"
}

DELETE /pets/{petId}
Response: 204 No Content
(no body)

Modern PetstoreAPI verwendet korrekte HTTP-Statuscodes und enthält Location-Header für erstellte Ressourcen. Prüfen Sie den HTTP-Statuscodes-Leitfaden für die vollständige Zuordnung.

4. Bloße Arrays ohne Metadaten

Der Verstoß:

GET /pet/findByStatus?status=available
Response: 200 OK
[
  {"id": 1, "name": "Fluffy"},
  {"id": 2, "name": "Buddy"}
]

Warum es falsch ist:

Die Rückgabe bloßer Arrays schafft Probleme:

Die Lösung von Modern PetstoreAPI:

GET /pets?status=AVAILABLE
Response: 200 OK
{
  "data": [
    {"id": "019b4132-70aa-764f-b315-e2803d882a24", "name": "Fluffy"},
    {"id": "019b4127-54d5-76d9-b626-0d4c7bfce5b6", "name": "Buddy"}
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "totalItems": 45,
    "totalPages": 3
  },
  "links": {
    "self": "/pets?status=AVAILABLE&page=1",
    "next": "/pets?status=AVAILABLE&page=2",
    "last": "/pets?status=AVAILABLE&page=3"
  }
}

Modern PetstoreAPI umschließt alle Sammlungen in Objekten mit Metadaten und HATEOAS-Links. Siehe den Paginierungsleitfaden für Implementierungsdetails.

5. Fehlende Fehlerstandards

Der Verstoß:

Response: 400 Bad Request
{
  "code": 400,
  "message": "Invalid input"
}

Warum es falsch ist:

Dieses Fehlerformat ist nicht standardisiert und liefert minimale Informationen:

Die Lösung von Modern PetstoreAPI:

Response: 400 Bad Request
Content-Type: application/problem+json
{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/pets",
  "errors": [
    {
      "field": "name",
      "message": "Name is required",
      "code": "REQUIRED_FIELD"
    },
    {
      "field": "status",
      "message": "Status must be one of: AVAILABLE, PENDING, SOLD",
      "code": "INVALID_ENUM"
    }
  ]
}

Modern PetstoreAPI verwendet RFC 9457 Problem Details für alle Fehler. Siehe den Fehlerbehandlungsleitfaden für das vollständige Fehlerformat.

Sicherheitskatastrophen im alten Design

Abgesehen von REST-Verstößen weist der Swagger Petstore schwerwiegende Sicherheitsprobleme auf.

GET-Anfrage mit Passwörtern

Der Verstoß:

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

Warum es eine Katastrophe ist:

Passwörter in GET-Anfragen erscheinen in:

Dies ist eine kritische Sicherheitslücke. Passwörter sollten niemals in URLs enthalten sein.

Die Lösung von Modern PetstoreAPI:

POST /auth/login
Content-Type: application/json
{
  "username": "john",
  "password": "secret123"
}

Response: 200 OK
{
  "accessToken": "eyJhbGc...",
  "refreshToken": "eyJhbGc...",
  "expiresIn": 3600
}

Modern PetstoreAPI verwendet POST für die Authentifizierung mit JSON-Bodies. Passwörter erscheinen niemals in URLs. Siehe den Authentifizierungsleitfaden für OAuth 2.0- und JWT-Muster.

API-Schlüssel in Abfrageparametern

Der Verstoß:

GET /pet/123?api_key=abc123secret

Warum es falsch ist:

API-Schlüssel in Abfrageparametern haben die gleichen Probleme wie Passwörter in URLs:

Die Lösung von Modern PetstoreAPI:

GET /pets/019b4132-70aa-764f-b315-e2803d882a24
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Modern PetstoreAPI verwendet standardmäßige Authorization-Header für API-Schlüssel und Tokens. Siehe den Sicherheitsleitfaden für Authentifizierungsmuster.

Wie Modern PetstoreAPI diese Probleme behebt

Modern PetstoreAPI wurde von Grund auf neu entwickelt, um ein korrektes REST-API-Design zu demonstrieren. Hier ist, was es anders macht:

Produktionsreifes REST-Design

Moderne Standards

Unterstützung mehrerer Protokolle

Im Gegensatz zum Swagger Petstore (nur REST) unterstützt Modern PetstoreAPI:

Siehe den Protokolle-Leitfaden für Implementierungsdetails.

Echte Geschäftslogik

Modern PetstoreAPI enthält realistische Funktionen:

Prüfen Sie die API-Dokumentation für den vollständigen Funktionsumfang.

REST-API-Design mit Apidog testen

Apidog hilft Ihnen, das REST-API-Design zu validieren und Verstöße zu erkennen, bevor sie in Produktion gehen.

OpenAPI-Spezifikationen importieren und validieren

# Modern PetstoreAPI-Spezifikation importieren
1. Apidog öffnen
2. Klicken Sie auf "Importieren" → "OpenAPI"
3. Geben Sie ein: https://petstoreapi.com/openapi.json
4. Apidog validiert die Spezifikation und erstellt Testfälle

Apidog erkennt automatisch:

REST-Prinzipien testen

Erstellen Sie Testfälle, die die REST-Konformität überprüfen:

Test: Ressourcennamen sind Plural

// Apidog Testskript
pm.test("Endpunkt verwendet Plural-Ressourcennamen", function() {
  const url = pm.request.url.toString();
  pm.expect(url).to.match(/\/pets\/|\/orders\/|\/users\//);
  pm.expect(url).to.not.match(/\/pet\/|\/order\/|\/user\//);
});

Test: Korrekte Statuscodes

pm.test("POST gibt 201 Created zurück", function() {
  if (pm.request.method === "POST") {
    pm.response.to.have.status(201);
    pm.response.to.have.header("Location");
  }
});

pm.test("DELETE gibt 204 No Content zurück", function() {
  if (pm.request.method === "DELETE") {
    pm.response.to.have.status(204);
    pm.expect(pm.response.text()).to.be.empty;
  }
});

Test: Sammlungen haben Metadaten

pm.test("Sammlungsantwort enthält Paginierung", function() {
  const response = pm.response.json();
  pm.expect(response).to.have.property("data");
  pm.expect(response).to.have.property("pagination");
  pm.expect(response.pagination).to.have.property("page");
  pm.expect(response.pagination).to.have.property("totalItems");
});

Altes vs. neues Petstore vergleichen

Importieren Sie beide Spezifikationen in Apidog und führen Sie side-by-side Vergleiche durch:

  1. Swagger Petstore importieren: https://petstore.swagger.io/v2/swagger.json
  2. Modern PetstoreAPI importieren: https://petstoreapi.com/openapi.json
  3. Automatisierte Tests auf beiden ausführen
  4. Ergebnisse vergleichen, um die Unterschiede zu sehen

Apidog hebt die Designverstöße im Swagger Petstore hervor und zeigt, wie Modern PetstoreAPI diese behebt.

Migrationsleitfaden: Vom alten Petstore zum modernen Design

Wenn Sie eine API basierend auf dem Swagger Petstore erstellt haben, erfahren Sie hier, wie Sie zum korrekten REST-Design migrieren:

Schritt 1: Ressourcennamen korrigieren

Vorher:

GET /pet/{petId}
POST /pet
DELETE /pet/{petId}

Nachher:

GET /pets/{petId}
POST /pets
DELETE /pets/{petId}

Migrationsstrategie:

Schritt 2: Aktionsverben entfernen

Vorher:

GET /pet/findByStatus?status=available
GET /pet/findByTags?tags=tag1,tag2

Nachher:

GET /pets?status=AVAILABLE
GET /pets?tags=tag1,tag2

Migrationsstrategie:

Schritt 3: HTTP-Statuscodes korrigieren

Vorher:

POST /pet → 200 OK
DELETE /pet/{petId} → 200 OK mit Body

Nachher:

POST /pets → 201 Created mit Location-Header
DELETE /pets/{petId} → 204 No Content (kein Body)

Migrationsstrategie:

Schritt 4: Sammlungen verpacken

Vorher:

[
  {"id": 1, "name": "Fluffy"},
  {"id": 2, "name": "Buddy"}
]

Nachher:

{
  "data": [...],
  "pagination": {...},
  "links": {...}
}

Migrationsstrategie:

Schritt 5: RFC 9457 Fehler implementieren

Vorher:

{
  "code": 400,
  "message": "Invalid input"
}

Nachher:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [...]
}

Migrationsstrategie:

Praktische Auswirkungen schlechten API-Designs

Schlechtes API-Design hat reale Kosten:

Entwickler-Verwirrung

Wenn APIs gegen REST-Prinzipien verstoßen, verschwenden Entwickler Zeit:

Kosten: Stunden Entwicklerzeit pro Integration

Client-Fehler

Inkonsistente APIs führen zu clientseitigen Fehlern:

Kosten: Produktionsvorfälle und Kundenauswirkungen

Sicherheitslücken

Designfehler schaffen Sicherheitsrisiken:

Kosten: Datenlecks und Compliance-Verstöße

Technische Schulden

Schlechte Beispiele summieren sich im Laufe der Zeit:

Kosten: Langfristige Wartungslast

Fazit

Der Swagger Petstore erfüllte seinen Zweck als einfaches OpenAPI-Beispiel, aber es ist an der Zeit, weiterzugehen. Seine REST-Verstöße, Sicherheitsprobleme und Anti-Muster haben zu viele Produktions-APIs beeinflusst.

Modern PetstoreAPI bietet die Referenzimplementierung, die die Branche benötigt: korrektes REST-Design, moderne Standards, Multi-Protokoll-Unterstützung und produktionsreife Muster. Verwenden Sie es als Lernressource und Referenz für Ihr API-Design.

Testen Sie Ihre APIs mit Apidog, um Designverstöße frühzeitig zu erkennen. Importieren Sie Ihre OpenAPI-Spezifikationen, führen Sie automatisierte Tests durch und stellen Sie sicher, dass Ihre APIs REST-Prinzipien befolgen, bevor sie in Produktion gehen.

Nächste Schritte:

  1. Erkunden Sie die Modern PetstoreAPI-Dokumentation
  2. Vergleichen Sie Ihr API-Design mit den Mustern der Modern PetstoreAPI
  3. Importieren Sie Ihre OpenAPI-Spezifikation zur Validierung in Apidog
  4. Beheben Sie REST-Verstöße mithilfe des obigen Migrationsleitfadens
  5. Übernehmen Sie RFC 9457 für die Fehlerbehandlung

Die Ära der schlechten API-Beispiele ist vorbei. Bauen Sie APIs auf die richtige Weise mit Modern PetstoreAPI.

Häufig gestellte Fragen

Warum hat Swagger ein schlechtes Beispiel erstellt?

Der Swagger Petstore wurde 2011 als einfache Demonstration der Swagger-Spezifikation erstellt. Er war nicht als Referenz für das REST-API-Design gedacht. Das Problem ist, dass er zum De-facto-Standardbeispiel wurde und seine Fehler von Millionen von Entwicklern kopiert wurden.

Sollte ich Swagger Petstore nicht mehr verwenden?

Ja, für das Erlernen von REST-API-Design. Verwenden Sie stattdessen Modern PetstoreAPI. Es demonstriert korrekte REST-Prinzipien, moderne Standards und produktionsreife Muster. Der alte Petstore lehrt Anti-Muster, die Produktionssystemen schaden.

Ist Modern PetstoreAPI produktionsreif?

Ja. Modern PetstoreAPI enthält realistische Geschäftslogik, ordnungsgemäße Fehlerbehandlung, Authentifizierung, Ratenbegrenzung und Sicherheitsfunktionen. Sie können es mit minimalen Änderungen bereitstellen oder als Referenz für Ihr eigenes API-Design verwenden.

Wie teste ich, ob meine API REST-Prinzipien befolgt?

Importieren Sie Ihre OpenAPI-Spezifikation in Apidog und führen Sie automatisierte Tests durch. Apidog validiert Ressourcennamen, HTTP-Statuscodes, Antwortstrukturen und Sicherheitsmuster. Sie können Ihre API auch direkt mit Modern PetstoreAPI vergleichen.

Was ist der größte Fehler im Swagger Petstore?

Die Verwendung von GET /user/login mit Passwörtern in Abfrageparametern. Dies offenbart Passwörter im Browserverlauf, in Serverprotokollen und in Referrer-Headern – eine kritische Sicherheitslücke. Verwenden Sie für die Authentifizierung immer POST mit JSON-Bodies.

Kann ich schrittweise von Swagger Petstore Mustern migrieren?

Ja. Unterstützen Sie während einer Übergangsphase sowohl alte als auch neue Endpunkte. Fügen Sie veraltete Warnungen zu alten Endpunkten hinzu, aktualisieren Sie die Dokumentation und überwachen Sie die Nutzung. Entfernen Sie alte Endpunkte, nachdem Clients migriert sind (typischerweise 6-12 Monate).

Unterstützt Modern PetstoreAPI GraphQL und gRPC?

Ja. Im Gegensatz zum Swagger Petstore (nur REST) unterstützt Modern PetstoreAPI mehrere Protokolle: REST, GraphQL, gRPC, WebSocket, SSE, MQTT, Webhooks und MCP. Siehe den Protokolle-Leitfaden für Details.

Wie überzeuge ich mein Team, unser API-Design zu verbessern?

Zeigen Sie ihnen die realen Kosten: Entwicklerverwirrung, Client-Fehler, Sicherheitslücken und technische Schulden. Verwenden Sie Apidog, um die Verstöße in Ihrer aktuellen API zu demonstrieren. Vergleichen Sie Ihr Design mit der Modern PetstoreAPI und zeigen Sie die Verbesserungen auf.

Praktizieren Sie API Design-First in Apidog

Entdecken Sie eine einfachere Möglichkeit, APIs zu erstellen und zu nutzen

Kostenlos registrierenDownload
Schlechtes REST API Design: Warum Swagger Petstore ein schlechtes Beispiel ist