Communitygithub.com

API-Design-Prinzipien (REST & GraphQL)

Beherrsche die REST- und GraphQL-API-Designprinzipien, um intuitive, skalierbare und wartbare APIs zu erstellen, die Entwickler begeistern. Verwende diese Fähigkeit beim Entwurf neuer APIs, bei der Überprüfung von API-Spezifikationen oder bei der Festlegung von API-Designstandards.

Was ist API-Design-Prinzipien (REST & GraphQL)?

Diese Fähigkeit (Skill) vermittelt umfassende Prinzipien und praktische Muster für das Design von REST- und GraphQL-APIs. Sie ist ideal für Entwickler und Architekten, die neue APIs entwerfen, bestehende APIs überarbeiten oder API-Standards für ihr Team etablieren möchten. Die Fähigkeit behandelt Kernthemen wie RESTful-Design (ressourcenorientierte Architektur), GraphQL-Schema-First-Entwicklung, API-Versionierungsstrategien und häufige Fallstricke. Für REST werden konkrete Muster für Endpunkt-Design, Paginierung, Fehlerbehandlung und HATEOAS mit Python-Codebeispielen (FastAPI, Pydantic) bereitgestellt. Für GraphQL werden Schema-Design, Resolver-Logik und die Vermeidung des N+1-Problems mit DataLoadern anhand von Python-Code (Ariadne, aiodataloader) und GraphQL-Schema-Definitionen veranschaulicht. Der Skill betont Best Practices wie konsistente Namensgebung, korrekte HTTP-Statuscodes, Eingabevalidierung und Cursor-basierte Paginierung. Enthaltene Referenzen, Vorlagen und Checklisten helfen, die Konzepte in der täglichen Arbeit direkt anzuwenden.

Funktioniert mit✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry-data/tree/HEAD/api/api-design-principles-algusaem-algusaem-portfolio

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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 erstellen
  • PUT: Gesamte Ressource ersetzen (idempotent)
  • PATCH: Teilweise Ressourcenaktualisierung
  • DELETE: 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

  1. Konsistente Benennung: Verwende Plural-Nomen für Sammlungen (/users, nicht /user)
  2. Zustandslos: Jede Anfrage enthält alle notwendigen Informationen
  3. HTTP-Statuscodes korrekt verwenden: 2xx Erfolg, 4xx Client-Fehler, 5xx Server-Fehler
  4. API versionieren: Plane von Anfang an für bahnbrechende Änderungen
  5. Paginierung: Paginiere große Sammlungen immer
  6. Ratenbegrenzung: Schütze deine API mit Ratenbegrenzungen
  7. Dokumentation: Verwende OpenAPI/Swagger für interaktive Dokumentation

GraphQL-APIs

  1. Schema zuerst: Entwerfe das Schema, bevor du Resolver schreibst
  2. N+1 vermeiden: Verwende DataLoader für effizientes Datenabrufen
  3. Eingabevalidierung: Validiere auf Schema- und Resolver-Ebene
  4. Fehlerbehandlung: Gib strukturierte Fehler in Mutations-Nutzlasten zurück
  5. Paginierung: Verwende Cursor-basierte Paginierung (Relay-Spezifikation)
  6. Veraltung: Verwende die Direktive @deprecated für schrittweise Migration
  7. Ü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

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry-data

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry-data

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry-data

Speech-to-text transcription and translation via OpenAI Audio API -- models, response formats, timestamps, prompting, streaming, chunking, and diarization

majiayu000/claude-skill-registry-data

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry-data

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry-data

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry-data

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

majiayu000/claude-skill-registry-data

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry-data

Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".

majiayu000/claude-skill-registry-data

Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".

majiayu000/claude-skill-registry-data

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

Verwandte Skills