API-Design: Das "Kommunikationsprotokoll" zwischen Frontend und Backend

🎯 Kernfrage

Wie kommunizieren Frontend und Backend effizient miteinander? Das ist wie die Frage: Wie sollte die Speisekarte eines Restaurants gestaltet sein, damit die Gäste sie sofort verstehen? Wie merkt sich der Kellner die Bestellungen, ohne Fehler zu machen? Wie wird das Servieren standardisiert, damit die Gäste zufrieden sind? API-Design löst das Problem der "Kommunikationsregeln".

0. Zuerst eine Frage: Hast du diese Albträume schon erlebt?

Szenario 1: Beliebige Benennung von Schnittstellen

GET /getUserData
GET /fetchUserInfo
GET /queryUserById
GET /users/query

Vier Schnittstellen, gleiche Funktion, völlig unterschiedliche Benennungsstile. Neue Mitarbeiter stehen vor einem Rätsel: Welche soll ich verwenden?

Szenario 2: Fehlerbehandlung ist chaotisch

json

// Manche geben den HTTP-Statuscode zurück
HTTP/1.1 404 Not Found

// Manche geben 200 + code zurück
HTTP/1.1 200 OK
{ "code": 404, "message": "Benutzer nicht gefunden" }

// Manche werfen einfach eine Ausnahme
HTTP/1.1 200 OK
{ "error": "Ein Fehler ist aufgetreten" }

Das Frontend weiß nicht, wie es feststellen soll, ob die Anfrage erfolgreich war.

Szenario 3: Die Antwortstruktur ist bei jedem unterschiedlich

json

// Schnittstelle A
{ "data": { ... } }

// Schnittstelle B
{ "result": { ... } }

// Schnittstelle C
{ "content": { ... } }

Jede Schnittstelle hat ein anderes Rückgabeformat. Das Frontend muss jede Schnittstelle einzeln behandeln.

Gutes API-Design ist wie das Bestellsystem eines Restaurants — klare Speisekarte, standardisierte Abläufe, hilfreiche Fehlermeldungen.

1. Was ist eine API?

API (Application Programming Interface, Schnittstelle zur Anwendungsprogrammierung) ist die "Vereinbarung für die Kommunikation zwischen Programmen".

1.1 Analogie mit einem Restaurant

Restaurant-Rolle	Entsprechendes Konzept	Beschreibung
Speisekarte	API-Dokumentation	Sagt dir, welche "Gerichte" bestellt werden können
Kellner	HTTP-Protokoll	Standardisierte "Kommunikationsweise"
Küche	Server	Verarbeitet "Bestellungen"
Servieren	Antwort	Liefert das Ergebnis an den "Gast"

1.2 Eine vollständige API-Anfrage

👇 Probier es aus: Klicke auf die Schaltfläche unten und beobachte den vollständigen Ablauf einer API-Anfrage-Antwort:

API Request Demo

// Click a command below to simulate API requests

> ▋

💻ClientSends request

Waiting for request...

HTTP Request→

🖥️ServerHandles request

Waiting...

HTTP Response←

📦ResponseReturns result

Waiting for response...

💡 Click a command button to observe a complete API request-response flow.

2. API-Design-Philosophie: RPC / REST / GraphQL / gRPC

Bevor wir uns mit dem konkreten RESTful-Design befassen, lassen Sie uns vier vorherrschende API-Designstile kennenlernen:

REST

Most common

Representational State Transfer was introduced by Roy Fielding in 2000. It models the system as resources identified by URLs and operated on with HTTP methods.

Example: fetch user information

GET    /users           # Fetch user list
GET    /users/123       # Fetch one user
POST   /users           # Create user
PUT    /users/123       # Full update
PATCH  /users/123       # Partial update
DELETE /users/123       # Delete user

Key features

✓URLs are nouns, not verbs

✓HTTP methods express actions

✓Stateless requests carry all needed context

✓Cacheable and friendly to layered systems

Use casesPublic APIs, CRUD operations, and domains with clear resource boundaries

Official sitehttps://restfulapi.net/

📊 Style quick comparison

Feature

RPC

REST

GraphQL

gRPC

Core idea

Procedure-oriented

Resource-oriented

Data-oriented

Method-oriented

URL style

Verb-first

Noun-first

Single endpoint

URL-independent

Learning curve

Low

Medium

High

Performance

Average

Good

Excellent

Usage share

~30%

~50%

~15%

~5%

2.1 REST vs RESTful: Was ist der Unterschied?

Viele verwechseln diese beiden Konzepte:

Konzept	Bedeutung	Beschreibung
REST	Ein Architekturstil	Ein von Roy Fielding vorgeschlagenes Designkonzept mit einer Reihe von Einschränkungen
RESTful	Entspricht dem REST-Stil	Adjektiv, bedeutet, dass das API-Design den REST-Prinzipien folgt

Analogie:

REST ist wie "Minimalismus" — ein Designkonzept
Eine RESTful-API ist wie ein " minimalistisch eingerichteter Raum" — eine konkrete Umsetzung dieses Konzepts

Die sechs Einschränkungen von REST:

Einschränkung	Beschreibung
Client-Server-Trennung	Frontend und Backend werden unabhängig voneinander entwickelt, Schnittstellen sind entkoppelt
Zustandslosigkeit	Jede Anfrage enthält alle notwendigen Informationen, der Server speichert keinen Sitzungsstatus
Cachebarkeit	Antworten sollten angeben, ob sie zwischengespeichert werden können, um die Leistung zu verbessern
Einheitliche Schnittstelle	Verwendung standardmäßiger HTTP-Methoden und Statuscodes
Schichtensystem	Der Client muss nicht wissen, mit welcher Server-Schicht er verbunden ist
Code on Demand (optional)	Der Server kann die Client-Funktionalität erweitern

💡 Warum ist REST am weitesten verbreitet?

Niedrige Lernkurve: Das HTTP-Protokoll selbst verkörpert bereits das REST-Konzept
Ausgereiftes Ökosystem: Reichhaltige Tools, Frameworks und Dokumentation
Hohe Universalität: Jede Sprache, jede Plattform kann es aufrufen
Einfaches Caching: GET-Anfragen sind von Natur aus cachebar, CDN-freundlich

3. RESTful-Design: URLs zum Sprechen bringen

REST (Representational State Transfer) ist ein Architekturstil mit folgenden Kernideen:

Dinge im Netzwerk als "Ressourcen" (Resource) abstrahieren
Ressourcen durch URLs identifizieren
Ressourcen durch HTTP-Methoden bearbeiten

3.1 Analogie mit einem Lagerhaus

Lagerhaus-Konzept	REST-Entsprechung	Beispiel
Regaladresse	URL	`/users`, `/orders`
Bearbeitungsweise	HTTP-Methode	GET (ansehen), POST (einlagern)
Ware	Ressource	Benutzerdaten, Bestelldaten

Schlüsselprinzip: URLs sind Substantive, keine Verben.

3.2 URL-Designregeln

Regel	Falsches Beispiel	Richtiges Beispiel	Beschreibung
Substantive statt Verben	`/getUsers`	`/users`	URL repräsentiert Ressourcen, HTTP-Methoden repräsentieren Aktionen
Pluralform verwenden	`/user`	`/users`	Einheitlicher Pluralstil
Kleinschreibung + Bindestriche	`/UserProfiles`	`/user-profiles`	URLs sind case-sensitive
Zu tiefe Hierarchien vermeiden	`/a/b/c/d/e`	`/a/b/c`	Maximal 3 Ebenen
Filter mit Abfrageparametern	`/products/phone/5000`	`/products?cat=phone`	Filterbedingungen mit `?`-Parametern

💡 URLs sind case-sensitive

Kleinschreibung + Bindestriche (-) ist die sicherste Methode, um Verwirrung bei Groß-/Kleinschreibung und Inkonsistenzen beim Unterstrich-Stil zu vermeiden.

3.3 HTTP-Methoden-Auswahl

Methode	Zweck	Idempotenz	Sicherheit	Typische Szenarien
GET	Ressource abrufen	Ja	Ja	Listen abfragen, Details anzeigen
POST	Ressource erstellen	Nein	Nein	Neuen Benutzer anlegen, Bestellung aufgeben
PUT	Vollständige Aktualisierung	Ja	Nein	Gesamte Benutzerdaten ersetzen
PATCH	Teilaktualisierung	Nein	Nein	Nur den Spitznamen ändern
DELETE	Ressource löschen	Ja	Nein	Benutzer löschen, Bestellung stornieren

💡 Was ist Idempotenz?

Idempotenz: Mehrmalige Ausführung führt zum gleichen Ergebnis.

Idempotente Operationen (GET/PUT/DELETE): 10 Mal klicken hat das gleiche Ergebnis wie 1 Mal
Nicht-idempotente Operationen (POST): 10 Mal klicken kann 10 Bestellungen erstellen

Lösung: POST-Operationen mit eindeutiger ID überprüfen, um doppelte Verarbeitung zu vermeiden.

4. Statuscodes: Fehler zum "Sprechen" bringen

HTTP-Statuscodes sind die Standardmethode des Servers, dem Client mitzuteilen, "was passiert ist".

4.1 Statuscode-Kategorien

Kategorie	Bedeutung	Typische Statuscodes
2xx	Erfolg	200 OK, 201 Created, 204 No Content
3xx	Umleitung	301 Permanent verschoben, 304 Nicht geändert
4xx	Client-Fehler	400 Parameterfehler, 401 Nicht authentifiziert, 404 Nicht gefunden
5xx	Server-Fehler	500 Interner Fehler, 503 Dienst nicht verfügbar

4.2 Demo der häufigsten Statuscodes

👇 Probier es aus: Klicke auf die Schaltfläche unten, um die Bedeutung häufiger Statuscodes zu verstehen:

HTTP Status Code Demo

// Click a button to inspect status code meanings

> ▋

✅2xx Success

200OKRequest succeeded

201CreatedResource created

204No ContentSucceeded with no response body

⚠️4xx Client errors

400Bad RequestMalformed request

401UnauthorizedNot authenticated

403ForbiddenNo permission

404Not FoundResource missing

422UnprocessableSemantic validation error

429Too ManyToo many requests

🔴5xx Server errors

500Server ErrorInternal server error

502Bad GatewayGateway error

503UnavailableService unavailable

💡 Click a command button to learn common HTTP status codes.

5. Fehlerbehandlung: Elegant "ablehnen"

Gute Fehlerbehandlung ermöglicht es dem Client, "den Statuscode zu sehen und zu wissen, was los ist", anstatt raten zu müssen.

4.1 "Fallen" bei der Fehlerbehandlung

Falle 1: Alle Fehler geben 200 zurück

json

// ❌ Falsche Vorgehensweise
HTTP/1.1 200 OK
{ "error": "Ein Fehler ist aufgetreten" }

Problem: Die Caching-Schicht wird diese "erfolgreiche" Antwort zwischenspeichern, und das Überwachungssystem kann das Problem nicht erkennen.

Falle 2: Fehlermeldungen sind zu vage

json

// ❌ Falsche Vorgehensweise
HTTP/1.1 400 Bad Request
{ "message": "Parameterfehler" }

Problem: Der Client weiß nicht, welcher Parameter falsch ist und warum.

Falle 3: Vertrauliche Informationen preisgeben

json

// ❌ Gefährliche Vorgehensweise
HTTP/1.1 500 Internal Server Error
{ "stack": "at UserService.login...", "sql": "SELECT * FROM..." }

Gefahr: Die Codestruktur und Datenbankabfragen werden offengelegt, was Angreifer ausnutzen können.

5.2 Demo der richtigen Fehlerbehandlung

👇 Probier es aus: Vergleiche "gute" und "schlechte" Fehlerantwort-Designs:

Error Handling Demo

// Compare poor and good error handling

> ▋

Response structure

Click a button above to view an error response example

💡 Click a button to compare poor and good error response design.

6. Versionsverwaltung: "Abwärtskompatibilität" der API

6.1 Warum Versionsverwaltung?

Szenario: Deine App hat 1 Million Benutzer und du musst die Bestellschnittstelle ändern.

Ohne Versionsverwaltung:

Neue App ruft neue Schnittstelle auf → normal
Alte App ruft neue Schnittstelle auf → fehlende Felder, Absturz!

Richtige Vorgehensweise:

/v1/orders — alte Schnittstelle, bedient weiterhin die alte App
/v2/orders — neue Schnittstelle, neue Funktionen hier

6.2 Strategien für die Versionsverwaltung

Strategie	Beispiel	Vorteile	Nachteile
URL-Pfad	`/v1/users`	Intuitiv, einfach zu cachen	URL wird länger
Anfrage-Header	`Accept: vnd.api.v2+json`	Saubere URL	Schwerer zu debuggen
Abfrageparameter	`/users?version=2`	Einfach	Weniger standardisiert

6.3 Beispiel für die Versionsentwicklung

Am Beispiel der Benutzerschnittstelle wird die Entwicklung von v1 zu v2 gezeigt:

Schnittstelle	v1 (alte Version)	v2 (neue Version)	Änderungsbeschreibung
Benutzer abrufen	`GET /v1/users` Rückgabe: `name, email`	`GET /v2/users` Rückgabe: `name, email, avatar, phone`	Neue Felder für Avatar und Telefonnummer
Bestellung erstellen	`POST /v1/orders` Akzeptiert: `items[]`	`POST /v2/orders` Akzeptiert: `items[], coupons[]`	Unterstützung für Gutscheine hinzugefügt
Stapelverarbeitung	Keine	`POST /v2/orders/batch`	Neue Schnittstelle für Stapelerstellung

💡 Best Practices für die Versionsverwaltung

Abwärtskompatibilität beibehalten: v1-Schnittstellen mindestens 6-12 Monate pflegen, um dem Client Zeit für Upgrades zu geben
Dokumentation synchron aktualisieren: Jede Version hat eine eigene API-Dokumentation
Verfallsankündigung: Vorab mitteilen, wann v1 abgeschaltet wird, und zur Migration auffordern
Nutzung überwachen: v1-Aufrufstatistiken erfassen und erst sicher abschalten, wenn bestätigt ist, dass es sicher ist

7. Antwortstruktur-Design

Die Antwortstruktur ist der "Datenvertrag" der Frontend-Backend-Zusammenarbeit. Ein einheitliches Format kann die Kommunikationskosten erheblich senken.

Why use a unified response format?

❌ Problem: endpoints return inconsistent shapes

// Endpoint A
{ "data": { "user": {...} } }

// Endpoint B
{ "result": { "user": {...} } }

// Endpoint C
{ "user": {...} }

The frontend must handle every endpoint separately, which creates duplicate and fragile code.

✅ Solution: unified response format

{
  "code": 0,
  "message": "success",
  "data": { ... },
  "request_id": "req-xxx"
}

💡Use request_id for troubleshooting. UUID v4 or Snowflake IDs are common choices.

7.1 Referenz: Best Practices großer Unternehmen

Google API-Designrichtlinien

Gemäß Google API Design Guide verlangt Google, dass alle API-Fehlerantworten eine google.rpc.Status-Nachrichtenstruktur enthalten:

json

{
  "error": {
    "code": 429,
    "message": "Ressourcen knapp, bitte versuchen Sie es später erneut",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_AVAILABILITY",
        "domain": "compute.googleapis.com",
        "metadata": {
          "zone": "us-east1-a",
          "service": "compute"
        }
      }
    ]
  }
}

Kernanforderungen:

Muss ErrorInfo enthalten, um maschinenlesbare Fehlerkennungen bereitzustellen
message richtet sich an Entwickler und beschreibt das Problem und die Lösung in knapper Sprache
Das details-Array kann LocalizedMessage (lokalisierte Nachrichten), Help (Hilfelinks) usw. enthalten

Microsoft REST-API-Richtlinien

Gemäß Microsoft REST API Guidelines betont Microsoft die Konsistenz von Antworten:

Klassifizierung von Fehlern und Störungen:

Fehler (Error): Client sendet ungültige Daten, gibt 4xx zurück, beeinträchtigt nicht die API-Verfügbarkeit
Störung (Fault): Server kann gültige Anfrage nicht korrekt beantworten, gibt 5xx zurück, beeinträchtigt die API-Verfügbarkeit

Antwort-Header-Spezifikation:

Date: Muss zurückgegeben werden, RFC 5322-Format (GMT-Zeitzone)
Content-Type: Muss zurückgegeben werden
ETag: Muss für Ressourcen zurückgegeben werden, die optimistische Nebenläufigkeitssteuerung unterstützen

Alibaba Java-Entwicklungshandbuch

Gemäß Alibaba Java Development Manual hat Alibaba folgende Spezifikationen für API-Antworten:

Einheitliches Rückgabeobjekt:

java

public class Result<T> {
    private Integer code;
    private String message;
    private T data;
    private String requestId;
}

Fehlercode-Segmentdesign:

Bereich	Typ	Beispiel
0	Erfolg	0
1xxxx	Parameterfehler	10001 Pflichtparameter fehlt
2xxxx	Geschäftsfehler	20001 Guthaben nicht ausreichend
3xxxx	Authentifizierungsfehler	30001 Nicht angemeldet
5xxxx	Systemfehler	50001 Datenbankausnahme

Stripe API-Antwort-Design

Gemäß Stripe API Documentation ist das Stripe-Fehlerantwort-Design sehr detailliert:

json

{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "Your card was declined.",
    "param": "number",
    "decline_code": "insufficient_funds",
    "doc_url": "https://stripe.com/docs/error-codes/card-declined"
  }
}

Design-Highlights:

type unterscheidet Fehlertypen: api_error, card_error, invalid_request_error
param gibt an, welcher Parameter genau falsch ist, das Frontend kann das Formularfeld direkt lokalisieren
doc_url bietet einen Dokumentationslink, Entwickler können sich tiefer informieren
decline_code bietet feingranularere Fehlerursachen

JSON:API-Spezifikation

Gemäß JSON:API Specification ist dies eine weithin akzeptierte JSON-API-Antwort-Spezifikation:

json

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API-Spezifikation im Detail"
    },
    "relationships": {
      "author": {
        "data": { "type": "users", "id": "9" }
      }
    }
  },
  "included": [
    {
      "type": "users",
      "id": "9",
      "attributes": {
        "name": "Max Mustermann"
      }
    }
  ]
}

Kern-Design:

data enthält die Hauptressource, muss type und id haben
attributes speichert Ressourcenattribute
relationships beschreibt Ressourcenverknüpfungen
included vermeidet doppelte Anfragen und liefert verknüpfte Daten auf einmal

GitHub REST-API-Antwort-Design

Gemäß GitHub REST API Documentation legt das GitHub-Antwort-Design Wert auf Entwicklererfahrung:

Erfolgsantwort:

json

{
  "id": 1296269,
  "node_id": "MDEwOlJlcG9zaXRvcnkxMjk2MjY5",
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "owner": {
    "login": "octocat",
    "id": 1,
    "avatar_url": "https://github.com/images/error/octocat_happy.gif"
  },
  "private": false,
  "html_url": "https://github.com/octocat/Hello-World"
}

Fehlerantwort:

json

{
  "message": "Bad credentials",
  "documentation_url": "https://docs.github.com/rest"
}

Design-Highlights:

Antwort enthält verschiedene URL-Formate (html_url, url) für unterschiedliche Verwendungszwecke
Fehlerantwort enthält documentation_url, das auf die Dokumentation verweist
Verwendet Link-Antwort-Header für die Paginierungsnavigation

Twitter/X API v2-Antwort-Design

Gemäß Twitter API v2 Documentation verwendet die Twitter API v2 ein schlankes Antwortformat:

json

{
  "data": {
    "id": "1460323737035677698",
    "text": "Hello, Twitter!"
  },
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "name": "Twitter Dev",
        "username": "TwitterDev"
      }
    ]
  }
}

Design-Highlights:

data enthält die Hauptdaten, includes enthält verknüpfte Daten (ähnlich wie JSON:API)
Unterstützt Feldauswahl: ?tweet.fields=created_at,public_metrics
Paginierung verwendet next_token und previous_token

7.2 Zusammenfassung der Best Practices

Unter Berücksichtigung der obigen Spezifikationen sollte das Antwortstruktur-Design folgenden Prinzipien folgen:

Konsistenz zuerst: Alle Schnittstellen verwenden die gleiche Antwortstruktur, das Frontend kann eine einheitliche Anfrageschicht kapseln
Maschinenlesbar: Fehlercode + Fehlerursache (reason) ermöglichen es Programmen, automatisch zu reagieren
Menschenfreundlich: message beschreibt klar und enthält Lösungsvorschläge
Nachverfolgbar: request_id durchläuft die gesamte Anfragekette, erleichtert die Problemlokalisierung
Internationalisierungsunterstützung: Durch details-Erweiterung lokalisierte Nachrichten bereitstellen

7.3 Datenfeld-Design-Spezifikation

data ist der Kern der Antwort, sein Design beeinflusst direkt die Frontend-Entwicklungseffizienz.

Single object vs list

Single object

{
  "code": 0,
  "data": {
    "id": 123,
    "name": "Alice"
  }
}

List

{
  "code": 0,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "total": 100
    }
  }
}

List data should be wrapped in items, with pagination metadata in pagination.

💡Follow ISO 8601 for time values and keep JSON field names in snake_case.

7.4 Erweitertes Fehlerantwort-Design

Validation errors

{
  "code": 10001,
  "message": "Validation failed",
  "data": {
    "errors": [
      {
        "field": "email",
        "message": "Invalid email format",
        "value": "invalid-email"
      },
      {
        "field": "password",
        "message": "Password must be at least 8 characters",
        "value": "123"
      }
    ]
  }
}

fieldField name, so the frontend can locate the form input

messageUser-friendly error description

valueSubmitted value from the client, optional

💡Error messages should be machine-readable and human-friendly so the frontend can handle them consistently.

Referenzlinks

8. Praxis: E-Commerce-System API-Design-Beispiel

# Benutzermodul
GET    /v1/users                    # Benutzerliste abrufen
POST   /v1/users                    # Neuen Benutzer erstellen
GET    /v1/users/{id}               # Benutzerdetails abrufen
PUT    /v1/users/{id}               # Benutzer vollständig aktualisieren
PATCH  /v1/users/{id}               # Benutzer teilweise aktualisieren
DELETE /v1/users/{id}               # Benutzer löschen

# Bestellmodul
GET    /v1/users/{id}/orders        # Bestellungen eines Benutzers abrufen
POST   /v1/orders                   # Bestellung erstellen
GET    /v1/orders/{id}              # Bestelldetails abrufen
PATCH  /v1/orders/{id}/status       # Bestellstatus aktualisieren

# Produktmodul (komplexe Filter mit Abfrageparametern)
GET    /v1/products?category=phone&price_max=5000&sort=price_desc&page=1

9. API-Design mit KI-Unterstützung

KI kann helfen, schnell ein normkonformes API-Design zu erstellen. Der Schlüssel liegt darin, klaren Kontext und Einschränkungen bereitzustellen.

9.1 Prompt-Vorlage

Du bist ein erfahrener Backend-Architekt mit Expertise in RESTful-API-Design. Bitte entwerfe eine Reihe von API-Schnittstellen für mich.

## Geschäftshintergrund
[Beschreibe dein Geschäftsszenario, z.B.: E-Commerce-System, Blog-Plattform, Aufgabenverwaltung etc.]

## Funktionale Anforderungen
[Liste die benötigten Funktionsmodule auf, z.B.:
- Benutzerverwaltung: Registrierung, Anmeldung, persönliche Informationen
- Bestellverwaltung: Bestellung erstellen, Bestellungen abfragen, Bestellung stornieren
- Produktverwaltung: Produktliste, Produktdetails, Suche]

## Designanforderungen
1. Befolge die RESTful-Spezifikation
2. URLs verwenden Substantive im Plural, Kleinschreibung + Bindestriche
3. Korrekte Verwendung von HTTP-Methoden (GET/POST/PUT/PATCH/DELETE)
4. Einheitliches Antwortformat: { code, message, data, request_id }
5. Angemessene Verwendung von Statuscodes
6. Versionsverwaltung: URL-Pfad-Methode (/v1/)

## Ausgabeformat
Bitte im folgenden Format ausgeben:

### Schnittstellenliste
| Methode | URL | Beschreibung | Anfragekörper | Antwortkörper |
|------|-----|------|--------|--------|

### Anfrage-/Antwortbeispiele
[Detailbeispiele für wichtige Schnittstellen]

### Statuscode-Erklärung
[Verwendete Statuscodes und ihre Bedeutung]

9.2 Praxisbeispiel: E-Commerce-Bestell-API

Eingabe-Prompt:

Du bist ein erfahrener Backend-Architekt mit Expertise in RESTful-API-Design. Bitte entwerfe eine Reihe von API-Schnittstellen für ein E-Commerce-Bestellsystem.

## Geschäftshintergrund
Eine B2C-E-Commerce-Plattform, auf der Benutzer Produkte durchsuchen, kaufen und den Bestellstatus einsehen können.

## Funktionale Anforderungen
- Bestellmodul: Bestellung erstellen, Bestellliste abfragen, Bestelldetails abfragen, Bestellung stornieren, Bestellung bezahlen
- Warenkorbmodul: Produkt hinzufügen, Menge ändern, Produkt entfernen, Warenkorb anzeigen

## Designanforderungen
1. Befolge die RESTful-Spezifikation
2. URLs verwenden Substantive im Plural, Kleinschreibung + Bindestriche
3. Korrekte Verwendung von HTTP-Methoden
4. Einheitliches Antwortformat
5. Versionsverwaltung: /v1/

KI-Ausgabebeispiel:

Methode	URL	Beschreibung
`POST`	`/v1/orders`	Bestellung erstellen
`GET`	`/v1/orders`	Bestellliste abfragen
`GET`	`/v1/orders/{id}`	Bestelldetails abfragen
`PATCH`	`/v1/orders/{id}/status`	Bestellstatus aktualisieren (stornieren/bezahlen)
`GET`	`/v1/users/{id}/cart`	Warenkorb abrufen
`POST`	`/v1/users/{id}/cart/items`	Produkt zum Warenkorb hinzufügen
`PATCH`	`/v1/users/{id}/cart/items/{itemId}`	Menge des Warenkorbprodukts ändern
`DELETE`	`/v1/users/{id}/cart/items/{itemId}`	Produkt aus dem Warenkorb entfernen

9.3 Hinweise zum KI-gestützten Design

Hinweis	Beschreibung
Vollständigen Kontext bereitstellen	Geschäftshintergrund, Benutzerrollen, Datenbeziehungen müssen klar beschrieben werden
Einschränkungen klar definieren	Benennungskonventionen, Versionsstrategie, Antwortformat im Voraus festlegen
Iterativ optimieren	Der erste Output ist möglicherweise nicht perfekt, Details nachfragen, Änderungen verlangen
Manuelle Überprüfung	KI-generierte Inhalte müssen manuell auf Übereinstimmung mit den Geschäftsanforderungen geprüft werden
Randfälle ergänzen	Die KI auffordern, Fehlerbehandlung, Berechtigungskontrolle, Paginierung und andere Randfälle zu berücksichtigen

💡 Nachfragetechniken

"Bitte ergänze Fehlerantwortbeispiele für jede Schnittstelle"
"Bitte berücksichtige Paginierung, Sortierung und Filterparameter"
"Bitte füge eine Beschreibung der Berechtigungskontrolle für die Schnittstellen hinzu"
"Bitte überprüfe, ob die Best Practices für RESTful eingehalten werden"

Glossar

Begriff	Englisch	Erklärung
API	Application Programming Interface	Vereinbarung für die Kommunikation zwischen Programmen
REST	Representational State Transfer	Ein Architekturstil, der URLs zur Identifizierung von Ressourcen verwendet
Ressource	Resource	Kernkonzept der REST-Architektur, hat eine eindeutige Kennung (URL)
Idempotenz	Idempotency	Mehrmalige Ausführung führt zum gleichen Ergebnis
Statuscode	Status Code	Der im HTTP-Protokoll definierte Antwortstatus
Versionsverwaltung	Versioning	Alte und neue APIs koexistieren lassen, reibungslose Upgrades ermöglichen
Anfragekörper	Request Body	Daten, die von POST/PUT/PATCH-Anfragen übertragen werden
Antwortkörper	Response Body	Vom Server zurückgegebene Daten
Header	Header	Metadaten der Anfrage/Antwort (z.B. Content-Type)
Authentifizierung	Authentication	Überprüfen "wer du bist" (Anmeldung, Token)
Autorisierung	Authorization	Überprüfen "was du tun darfst" (Berechtigungen)

API-Design: Das "Kommunikationsprotokoll" zwischen Frontend und Backend ​

0. Zuerst eine Frage: Hast du diese Albträume schon erlebt? ​

1. Was ist eine API? ​

1.1 Analogie mit einem Restaurant ​

1.2 Eine vollständige API-Anfrage ​

2. API-Design-Philosophie: RPC / REST / GraphQL / gRPC ​

REST

2.1 REST vs RESTful: Was ist der Unterschied? ​

3. RESTful-Design: URLs zum Sprechen bringen ​

3.1 Analogie mit einem Lagerhaus ​

3.2 URL-Designregeln ​

3.3 HTTP-Methoden-Auswahl ​

4. Statuscodes: Fehler zum "Sprechen" bringen ​

4.1 Statuscode-Kategorien ​

4.2 Demo der häufigsten Statuscodes ​

5. Fehlerbehandlung: Elegant "ablehnen" ​

4.1 "Fallen" bei der Fehlerbehandlung ​

5.2 Demo der richtigen Fehlerbehandlung ​

6. Versionsverwaltung: "Abwärtskompatibilität" der API ​

6.1 Warum Versionsverwaltung? ​

6.2 Strategien für die Versionsverwaltung ​

6.3 Beispiel für die Versionsentwicklung ​

7. Antwortstruktur-Design ​

Why use a unified response format?

7.1 Referenz: Best Practices großer Unternehmen ​

7.2 Zusammenfassung der Best Practices ​

7.3 Datenfeld-Design-Spezifikation ​

Single object vs list

7.4 Erweitertes Fehlerantwort-Design ​

Validation errors

8. Praxis: E-Commerce-System API-Design-Beispiel ​

9. API-Design mit KI-Unterstützung ​

9.1 Prompt-Vorlage ​

9.2 Praxisbeispiel: E-Commerce-Bestell-API ​

9.3 Hinweise zum KI-gestützten Design ​

Glossar ​

API-Design: Das "Kommunikationsprotokoll" zwischen Frontend und Backend

0. Zuerst eine Frage: Hast du diese Albträume schon erlebt?

1. Was ist eine API?

1.1 Analogie mit einem Restaurant

1.2 Eine vollständige API-Anfrage

2. API-Design-Philosophie: RPC / REST / GraphQL / gRPC

2.1 REST vs RESTful: Was ist der Unterschied?

3. RESTful-Design: URLs zum Sprechen bringen

3.1 Analogie mit einem Lagerhaus

3.2 URL-Designregeln

3.3 HTTP-Methoden-Auswahl

4. Statuscodes: Fehler zum "Sprechen" bringen

4.1 Statuscode-Kategorien

4.2 Demo der häufigsten Statuscodes

5. Fehlerbehandlung: Elegant "ablehnen"

4.1 "Fallen" bei der Fehlerbehandlung

5.2 Demo der richtigen Fehlerbehandlung

6. Versionsverwaltung: "Abwärtskompatibilität" der API

6.1 Warum Versionsverwaltung?

6.2 Strategien für die Versionsverwaltung

6.3 Beispiel für die Versionsentwicklung

7. Antwortstruktur-Design

7.1 Referenz: Best Practices großer Unternehmen

7.2 Zusammenfassung der Best Practices

7.3 Datenfeld-Design-Spezifikation

7.4 Erweitertes Fehlerantwort-Design

8. Praxis: E-Commerce-System API-Design-Beispiel

9. API-Design mit KI-Unterstützung

9.1 Prompt-Vorlage

9.2 Praxisbeispiel: E-Commerce-Bestell-API

9.3 Hinweise zum KI-gestützten Design

Glossar