Was macht API-Design-Prinzipien (REST & GraphQL)?
Beherrsche die REST- und GraphQL-API-Designprinzipien, um intuitive, skalierbare und wartbare APIs zu erstellen, die Entwickler begeistern und die Zeit überdauern.
Wann diese Fähigkeit angewendet werden sollte
- Entwurf neuer REST- oder GraphQL-APIs
- Überarbeitung bestehender APIs für eine bessere Benutzerfreundlichkeit
- Festlegung von API-Designstandards für dein Team
- Überprüfung von API-Spezifikationen vor der Implementierung
- Migration zwischen API-Paradigmen (REST zu GraphQL usw.)
- Erstellung entwicklerfreundlicher API-Dokumentation
- Optimierung von APIs für spezifische Anwendungsfälle (mobil, Drittanbieter-Integrationen)
Kernkonzepte
1. REST-Designprinzipien
Ressourcenorientierte Architektur
- Ressourcen sind Substantive (Benutzer, Bestellungen, Produkte), keine Verben
- Verwende HTTP-Methoden für Aktionen (GET, POST, PUT, PATCH, DELETE)
- URLs repräsentieren Ressourcenhierarchien
- Einheitliche Namenskonventionen
Semantik der HTTP-Methoden:
GET: Ressourcen abrufen (idempotent, sicher)POST: Neue Ressourcen erstellenPUT: Gesamte Ressource ersetzen (idempotent)PATCH: Teilweise RessourcenaktualisierungDELETE: Ressourcen entfernen (idempotent)
2. GraphQL-Designprinzipien
Schema-First-Entwicklung
- Typen definieren dein Domänenmodell
- Abfragen (Queries) zum Lesen von Daten
- Mutationen zum Ändern von Daten
- Abonnements (Subscriptions) für Echtzeit-Updates
Abfragestruktur:
- Clients fordern genau das an, was sie benötigen
- Einzelner Endpunkt, mehrere Operationen
- Stark typisiertes Schema
- Introspection integriert
3. API-Versionierungsstrategien
URL-Versionierung:
/api/v1/users
/api/v2/users
Header-Versionierung:
Accept: application/vnd.api+json; version=1
Query-Parameter-Versionierung:
/api/users?version=1
REST-API-Entwurfsmuster
Muster 1: Ressourcensammlungs-Design
# Gut: Ressourcenorientierte Endpunkte
GET /api/users # Benutzer auflisten (mit Paginierung)
POST /api/users # Benutzer erstellen
GET /api/users/{id} # Bestimmten Benutzer abrufen
PUT /api/users/{id} # Benutzer ersetzen
PATCH /api/users/{id} # Benutzerfelder aktualisieren
DELETE /api/users/{id} # Benutzer löschen
# Verschachtelte Ressourcen
GET /api/users/{id}/orders # Bestellungen eines Benutzers abrufen
POST /api/users/{id}/orders # Bestellung für Benutzer erstellen
# Schlecht: Aktionsorientierte Endpunkte (vermeiden)
POST /api/createUser
POST /api/getUserById
POST /api/deleteUser
Muster 2: Paginierung und Filterung
from typing import List, Optional
from pydantic import BaseModel, Field
class Paginierungsparameter(BaseModel):
seite: int = Field(1, ge=1, description="Seitennummer")
seiten_groesse: int = Field(20, ge=1, le=100, description="Elemente pro Seite")
class FilterParameter(BaseModel):
status: Optional[str] = None
erstellt_nach: Optional[str] = None
suche: Optional[str] = None
class PaginierteAntwort(BaseModel):
elemente: List[dict]
gesamt: int
seite: int
seiten_groesse: int
seiten: int
@property
def hat_naechste(self) -> bool:
return self.seite < self.seiten
@property
def hat_vorherige(self) -> bool:
return self.seite > 1
# FastAPI-Endpunktbeispiel
from fastapi import FastAPI, Query, Depends
app = FastAPI()
@app.get("/api/users", response_model=PaginierteAntwort)
async def benutzer_auflisten(
seite: int = Query(1, ge=1),
seiten_groesse: int = Query(20, ge=1, le=100),
status: Optional[str] = Query(None),
suche: Optional[str] = Query(None)
):
# Filter anwenden
abfrage = erstelle_abfrage(status=status, suche=suche)
# Gesamtanzahl zählen
gesamt = await zaehle_benutzer(abfrage)
# Seite abrufen
versatz = (seite - 1) * seiten_groesse
benutzer = await hole_benutzer(abfrage, limit=seiten_groesse, offset=versatz)
return PaginierteAntwort(
elemente=benutzer,
gesamt=gesamt,
seite=seite,
seiten_groesse=seiten_groesse,
seiten=(gesamt + seiten_groesse - 1) // seiten_groesse
)
Muster 3: Fehlerbehandlung und Statuscodes
from fastapi import HTTPException, status
from pydantic import BaseModel
class Fehlerantwort(BaseModel):
fehler: str
nachricht: str
details: Optional[dict] = None
zeitstempel: str
pfad: str
class ValidierungsfehlerDetail(BaseModel):
feld: str
nachricht: str
wert: Any
# Einheitliche Fehlerantworten
STATUS_CODES = {
"erfolg": 200,
"erstellt": 201,
"kein_inhalt": 204,
"ungueltige_anfrage": 400,
"nicht_authentifiziert": 401,
"verboten": 403,
"nicht_gefunden": 404,
"konflikt": 409,
"unverarbeitbar": 422,
"interner_fehler": 500
}
def melde_nicht_gefunden(ressource: str, id: str):
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail={
"fehler": "NichtGefunden",
"nachricht": f"{ressource} nicht gefunden",
"details": {"id": id}
}
)
def melde_validierungsfehler(fehler: List[ValidierungsfehlerDetail]):
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
detail={
"fehler": "Validierungsfehler",
"nachricht": "Anfragenvalidierung fehlgeschlagen",
"details": {"fehler": [f.model_dump() for f in fehler]}
}
)
# Beispielverwendung
@app.get("/api/users/{benutzer_id}")
async def benutzer_abrufen(benutzer_id: str):
benutzer = await hole_benutzer(benutzer_id)
if nicht benutzer:
melde_nicht_gefunden("Benutzer", benutzer_id)
return benutzer
Muster 4: HATEOAS (Hypermedia als Engine des Anwendungszustands)
class Benutzerantwort(BaseModel):
id: str
name: str
email: str
_links: dict
@classmethod
def von_benutzer(cls, benutzer: Benutzer, basis_url: str):
return cls(
id=benutzer.id,
name=benutzer.name,
email=benutzer.email,
_links={
"self": {"href": f"{basis_url}/api/users/{benutzer.id}"},
"orders": {"href": f"{basis_url}/api/users/{benutzer.id}/orders"},
"update": {
"href": f"{basis_url}/api/users/{benutzer.id}",
"method": "PATCH"
},
"delete": {
"href": f"{basis_url}/api/users/{benutzer.id}",
"method": "DELETE"
}
}
)
GraphQL-Designmuster
Muster 1: Schema-Design
# schema.graphql
# Klare Typdefinitionen
type User {
id: ID!
email: String!
name: String!
createdAt: DateTime!
# Beziehungen
orders(first: Int = 20, after: String, status: OrderStatus): OrderConnection!
profile: UserProfile
}
type Order {
id: ID!
status: OrderStatus!
total: Money!
items: [OrderItem!]!
createdAt: DateTime!
# Rückverweis
user: User!
}
# Paginierungsmuster (Relay-Stil)
type OrderConnection {
edges: [OrderEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type OrderEdge {
node: Order!
cursor: String!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
# Enums für Typsicherheit
enum OrderStatus {
PENDING
CONFIRMED
SHIPPED
DELIVERED
CANCELLED
}
# Benutzerdefinierte Skalare
scalar DateTime
scalar Money
# Abfrage-Wurzel
type Query {
user(id: ID!): User
users(first: Int = 20, after: String, search: String): UserConnection!
order(id: ID!): Order
}
# Mutations-Wurzel
type Mutation {
createUser(input: CreateUserInput!): CreateUserPayload!
updateUser(input: UpdateUserInput!): UpdateUserPayload!
deleteUser(id: ID!): DeleteUserPayload!
createOrder(input: CreateOrderInput!): CreateOrderPayload!
}
# Eingabetypen für Mutationen
input CreateUserInput {
email: String!
name: String!
password: String!
}
# Nutzlasttypen für Mutationen
type CreateUserPayload {
user: User
errors: [Error!]
}
type Error {
field: String
message: String!
}
Muster 2: Resolver-Design
from typing import Optional, List
from ariadne import QueryType, MutationType, ObjectType
from dataclasses import dataclass
query = QueryType()
mutation = MutationType()
user_type = ObjectType("User")
@query.field("user")
async def loese_benutzer(obj, info, id: str) -> Optional[dict]:
"""Löst einen einzelnen Benutzer anhand der ID auf."""
return await hole_benutzer_nach_id(id)
@query.field("users")
async def loese_benutzer_liste(
obj,
info,
first: int = 20,
after: Optional[str] = None,
search: Optional[str] = None
) -> dict:
"""Löst eine paginierte Benutzerliste auf."""
# Cursor dekodieren
versatz = dekodiere_cursor(after) if after else 0
# Benutzer abrufen
benutzer = await hole_benutzer_liste(
limit=first + 1, # Einen zusätzlichen abrufen, um hasNextPage zu prüfen
offset=versatz,
search=search
)
# Paginierung
hat_naechste = len(benutzer) > first
if hat_naechste:
benutzer = benutzer[:first]
kanten = [
{
"node": benutzer,
"cursor": kodiere_cursor(versatz + i)
}
for i, benutzer in enumerate(benutzer)
]
return {
"edges": kanten,
"pageInfo": {
"hasNextPage": hat_naechste,
"hasPreviousPage": versatz > 0,
"startCursor": kanten[0]["cursor"] if kanten else None,
"endCursor": kanten[-1]["cursor"] if kanten else None
},
"totalCount": await zaehle_benutzer(search=search)
}
@user_type.field("orders")
async def loese_benutzer_bestellungen(user: dict, info, first: int = 20) -> dict:
"""Löst die Bestellungen eines Benutzers auf (N+1-Prävention mit DataLoader)."""
# DataLoader für Batch-Anfragen verwenden
loader = info.context["loaders"]["orders_by_user"]
bestellungen = await loader.load(user["id"])
return paginiere_bestellungen(bestellungen, first)
@mutation.field("createUser")
async def loese_benutzer_erstellen(obj, info, input: dict) -> dict:
"""Erstellt einen neuen Benutzer."""
try:
# Eingabe validieren
validiere_benutzereingabe(input)
# Benutzer erstellen
benutzer = await erstelle_benutzer(
email=input["email"],
name=input["name"],
password=hashe_passwort(input["password"])
)
return {
"user": benutzer,
"errors": []
}
except Validierungsfehler as e:
return {
"user": None,
"errors": [{"field": e.field, "message": e.nachricht}]
}
Muster 3: DataLoader (N+1-Problem-Prävention)
from aiodataloader import DataLoader
from typing import List, Optional
class BenutzerLader(DataLoader):
"""Lädt Benutzer im Batch anhand der ID."""
async def batch_load_fn(self, benutzer_ids: List[str]) -> List[Optional[dict]]:
"""Lädt mehrere Benutzer in einer einzigen Abfrage."""
benutzer = await hole_benutzer_nach_ids(benutzer_ids)
# Ergebnisse der ursprünglichen Reihenfolge zuordnen
benutzer_map = {benutzer["id"]: benutzer for benutzer in benutzer}
return [benutzer_map.get(benutzer_id) for benutzer_id in benutzer_ids]
class BestellungenNachBenutzerLader(DataLoader):
"""Lädt Bestellungen im Batch anhand der Benutzer-ID."""
async def batch_load_fn(self, benutzer_ids: List[str]) -> List[List[dict]]:
"""Lädt Bestellungen für mehrere Benutzer in einer einzigen Abfrage."""
bestellungen = await hole_bestellungen_nach_benutzer_ids(benutzer_ids)
# Bestellungen nach user_id gruppieren
bestellungen_nach_benutzer = {}
for bestellung in bestellungen:
benutzer_id = bestellung["user_id"]
if benutzer_id nicht in bestellungen_nach_benutzer:
bestellungen_nach_benutzer[benutzer_id] = []
bestellungen_nach_benutzer[benutzer_id].append(bestellung)
# In der ursprünglichen Reihenfolge zurückgeben
return [bestellungen_nach_benutzer.get(benutzer_id, []) for benutzer_id in benutzer_ids]
# Kontext einrichten
def erstelle_kontext():
return {
"loaders": {
"user": BenutzerLader(),
"orders_by_user": BestellungenNachBenutzerLader()
}
}
Best Practices
REST-APIs
- Konsistente Benennung: Verwende Plural-Nomen für Sammlungen (
/users, nicht/user) - Zustandslos: Jede Anfrage enthält alle notwendigen Informationen
- HTTP-Statuscodes korrekt verwenden: 2xx Erfolg, 4xx Client-Fehler, 5xx Server-Fehler
- API versionieren: Plane von Anfang an für bahnbrechende Änderungen
- Paginierung: Paginiere große Sammlungen immer
- Ratenbegrenzung: Schütze deine API mit Ratenbegrenzungen
- Dokumentation: Verwende OpenAPI/Swagger für interaktive Dokumentation
GraphQL-APIs
- Schema zuerst: Entwerfe das Schema, bevor du Resolver schreibst
- N+1 vermeiden: Verwende DataLoader für effizientes Datenabrufen
- Eingabevalidierung: Validiere auf Schema- und Resolver-Ebene
- Fehlerbehandlung: Gib strukturierte Fehler in Mutations-Nutzlasten zurück
- Paginierung: Verwende Cursor-basierte Paginierung (Relay-Spezifikation)
- Veraltung: Verwende die Direktive
@deprecatedfür schrittweise Migration - Überwachung: Verfolge die Komplexität und Ausführungszeit von Abfragen
Häufige Fallstricke
- Over-fetching/Under-fetching (REST): In GraphQL behoben, erfordert aber DataLoader
- Bahnhbrechende Änderungen: Versioniere APIs oder verwende Veraltungsstrategien
- Inkonsistente Fehlerformate: Standardisiere Fehlerantworten
- Fehlende Ratenbegrenzungen: APIs ohne Limits sind anfällig für Missbrauch
- Schlechte Dokumentation: Undokumentierte APIs frustrieren Entwickler
- Ignorieren der HTTP-Semantik: POST für idempotente Operationen bricht Erwartungen
- Enge Kopplung: Die API-Struktur sollte nicht das Datenbankschema widerspiegeln
Ressourcen
- references/rest-best-practices.md: Umfassender Leitfaden für REST-API-Design
- references/graphql-schema-design.md: GraphQL-Schema-Muster und Anti-Patterns
- references/api-versioning-strategies.md: Versionierungsansätze und Migrationspfade
- assets/rest-api-template.py: FastAPI REST-API-Vorlage
- assets/graphql-schema-template.graphql: Vollständiges GraphQL-Schema-Beispiel
- assets/api-design-checklist.md: Checkliste für die Überprüfung vor der Implementierung
- scripts/openapi-generator.py: Generiert OpenAPI-Spezifikationen aus Code