Communitygithub.com

API-Design-Prinzipien

Beherrsche REST- und GraphQL-API-Designprinzipien, um intuitive, skalierbare und wartbare APIs zu entwickeln, die Entwickler begeistern. Nutze dies bei der Gestaltung neuer APIs, der Überprüfung von API-Spezifikationen oder der Festlegung von API-Designstandards.

Was ist API-Design-Prinzipien?

Diese Skill-Anleitung vermittelt umfassende Prinzipien und Muster für das Design von REST- und GraphQL-APIs. Sie deckt grundlegende Konzepte wie ressourcenorientierte Architektur, HTTP-Methoden-Semantik, Schema-First-Entwicklung und API-Versionierungsstrategien ab. Die Anleitung enthält praktische Codebeispiele in Python (FastAPI) und GraphQL für häufige Entwurfsmuster wie Paginierung, Fehlerbehandlung, HATEOAS und DataLoader zur Vermeidung von N+1-Problemen. Sie eignet sich ideal für Entwickler, die neue APIs entwerfen, bestehende APIs umgestalten oder API-Standards für ihr Team etablieren möchten. Die Skill-Inhalte sind plattformunabhängig und können mit Tools wie Claude Code, Cursor oder Codex verwendet werden.

Funktioniert mit✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry/tree/HEAD/skills/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?

Beherrsche REST- und GraphQL-API-Designprinzipien, um intuitive, skalierbare und wartbare APIs zu entwickeln, die Entwickler begeistern und die Zeit überdauern.

Wann Du Diese Skill Nutzen Solltest

  • Entwerfen neuer REST- oder GraphQL-APIs
  • Refactoring bestehender APIs für bessere Benutzerfreundlichkeit
  • Festlegen von API-Designstandards für Dein Team
  • Überprüfen von API-Spezifikationen vor der Implementierung
  • Migration zwischen API-Paradigmen (REST zu GraphQL usw.)
  • Erstellen entwicklerfreundlicher API-Dokumentation
  • Optimierung von APIs für spezifische Anwendungsfälle (mobil, Drittanbieter-Integrationen)

Kernkonzepte

1. RESTful-Designprinzipien

Ressourcenorientierte Architektur

  • Ressourcen sind Nomen (Benutzer, Bestellungen, Produkte), keine Verben
  • Verwende HTTP-Methoden für Aktionen (GET, POST, PUT, PATCH, DELETE)
  • URLs repräsentieren Ressourcenhierarchien
  • Einheitliche Namenskonventionen

HTTP-Methoden-Semantik:

  • GET: Ressourcen abrufen (idempotent, sicher)
  • POST: Neue Ressourcen erstellen
  • PUT: Vollständige 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
  • 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: Ressourcensammlungsdesign

# 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 des 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 PaginationParams(BaseModel):
    page: int = Field(1, ge=1, description="Seitennummer")
    page_size: int = Field(20, ge=1, le=100, description="Elemente pro Seite")

class FilterParams(BaseModel):
    status: Optional[str] = None
    created_after: Optional[str] = None
    search: Optional[str] = None

class PaginatedResponse(BaseModel):
    items: List[dict]
    total: int
    page: int
    page_size: int
    pages: int

    @property
    def has_next(self) -> bool:
        return self.page < self.pages

    @property
    def has_prev(self) -> bool:
        return self.page > 1

# FastAPI-Endpunktbeispiel
from fastapi import FastAPI, Query, Depends

app = FastAPI()

@app.get("/api/users", response_model=PaginatedResponse)
async def list_users(
    page: int = Query(1, ge=1),
    page_size: int = Query(20, ge=1, le=100),
    status: Optional[str] = Query(None),
    search: Optional[str] = Query(None)
):
    # Filter anwenden
    query = build_query(status=status, search=search)

    # Gesamtanzahl zählen
    total = await count_users(query)

    # Seite abrufen
    offset = (page - 1) * page_size
    users = await fetch_users(query, limit=page_size, offset=offset)

    return PaginatedResponse(
        items=users,
        total=total,
        page=page,
        page_size=page_size,
        pages=(total + page_size - 1) // page_size
    )

Muster 3: Fehlerbehandlung und Statuscodes

from fastapi import HTTPException, status
from pydantic import BaseModel

class ErrorResponse(BaseModel):
    error: str
    message: str
    details: Optional[dict] = None
    timestamp: str
    path: str

class ValidationErrorDetail(BaseModel):
    field: str
    message: str
    value: Any

# Einheitliche Fehlerantworten
STATUS_CODES = {
    "success": 200,
    "created": 201,
    "no_content": 204,
    "bad_request": 400,
    "unauthorized": 401,
    "forbidden": 403,
    "not_found": 404,
    "conflict": 409,
    "unprocessable": 422,
    "internal_error": 500
}

def raise_not_found(resource: str, id: str):
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail={
            "error": "NotFound",
            "message": f"{resource} nicht gefunden",
            "details": {"id": id}
        }
    )

def raise_validation_error(errors: List[ValidationErrorDetail]):
    raise HTTPException(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        detail={
            "error": "ValidationError",
            "message": "Anfragevalidierung fehlgeschlagen",
            "details": {"errors": [e.dict() for e in errors]}
        }
    )

# Beispielverwendung
@app.get("/api/users/{user_id}")
async def get_user(user_id: str):
    user = await fetch_user(user_id)
    if not user:
        raise_not_found("Benutzer", user_id)
    return user

Muster 4: HATEOAS (Hypermedia as the Engine of Application State)

class UserResponse(BaseModel):
    id: str
    name: str
    email: str
    _links: dict

    @classmethod
    def from_user(cls, user: User, base_url: str):
        return cls(
            id=user.id,
            name=user.name,
            email=user.email,
            _links={
                "self": {"href": f"{base_url}/api/users/{user.id}"},
                "orders": {"href": f"{base_url}/api/users/{user.id}/orders"},
                "update": {
                    "href": f"{base_url}/api/users/{user.id}",
                    "method": "PATCH"
                },
                "delete": {
                    "href": f"{base_url}/api/users/{user.id}",
                    "method": "DELETE"
                }
            }
        )

GraphQL-Entwurfsmuster

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ückreferenz
  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

# Query-Root
type Query {
  user(id: ID!): User
  users(first: Int = 20, after: String, search: String): UserConnection!

  order(id: ID!): Order
}

# Mutation-Root
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!
}

# Payload-Typen 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 resolve_user(obj, info, id: str) -> Optional[dict]:
    """Einzelnen Benutzer nach ID auflösen."""
    return await fetch_user_by_id(id)

@query.field("users")
async def resolve_users(
    obj,
    info,
    first: int = 20,
    after: Optional[str] = None,
    search: Optional[str] = None
) -> dict:
    """Paginierte Benutzerliste auflösen."""
    # Cursor dekodieren
    offset = decode_cursor(after) if after else 0

    # Benutzer abrufen
    users = await fetch_users(
        limit=first + 1,  # Einen extra abrufen, um hasNextPage zu prüfen
        offset=offset,
        search=search
    )

    # Paginierung
    has_next = len(users) > first
    if has_next:
        users = users[:first]

    edges = [
        {
            "node": user,
            "cursor": encode_cursor(offset + i)
        }
        for i, user in enumerate(users)
    ]

    return {
        "edges": edges,
        "pageInfo": {
            "hasNextPage": has_next,
            "hasPreviousPage": offset > 0,
            "startCursor": edges[0]["cursor"] if edges else None,
            "endCursor": edges[-1]["cursor"] if edges else None
        },
        "totalCount": await count_users(search=search)
    }

@user_type.field("orders")
async def resolve_user_orders(user: dict, info, first: int = 20) -> dict:
    """Bestellungen eines Benutzers auflösen (N+1-Prävention mit DataLoader)."""
    # DataLoader für Batch-Anfragen verwenden
    loader = info.context["loaders"]["orders_by_user"]
    orders = await loader.load(user["id"])

    return paginate_orders(orders, first)

@mutation.field("createUser")
async def resolve_create_user(obj, info, input: dict) -> dict:
    """Neuen Benutzer erstellen."""
    try:
        # Eingabe validieren
        validate_user_input(input)

        # Benutzer erstellen
        user = await create_user(
            email=input["email"],
            name=input["name"],
            password=hash_password(input["password"])
        )

        return {
            "user": user,
            "errors": []
        }
    except ValidationError as e:
        return {
            "user": None,
            "errors": [{"field": e.field, "message": e.message}]
        }

Muster 3: DataLoader (N+1-Problem-Prävention)

from aiodataloader import DataLoader
from typing import List, Optional

class UserLoader(DataLoader):
    """Batch-Laden von Benutzern nach ID."""

    async def batch_load_fn(self, user_ids: List[str]) -> List[Optional[dict]]:
        """Mehrere Benutzer in einer einzelnen Abfrage laden."""
        users = await fetch_users_by_ids(user_ids)

        # Ergebnisse der Eingabereihenfolge zuordnen
        user_map = {user["id"]: user for user in users}
        return [user_map.get(user_id) for user_id in user_ids]

class OrdersByUserLoader(DataLoader):
    """Batch-Laden von Bestellungen nach Benutzer-ID."""

    async def batch_load_fn(self, user_ids: List[str]) -> List[List[dict]]:
        """Bestellungen für mehrere Benutzer in einer einzelnen Abfrage laden."""
        orders = await fetch_orders_by_user_ids(user_ids)

        # Bestellungen nach user_id gruppieren
        orders_by_user = {}
        for order in orders:
            user_id = order["user_id"]
            if user_id not in orders_by_user:
                orders_by_user[user_id] = []
            orders_by_user[user_id].append(order)

        # In Eingabereihenfolge zurückgeben
        return [orders_by_user.get(user_id, []) for user_id in user_ids]

# Kontext-Setup
def create_context():
    return {
        "loaders": {
            "user": UserLoader(),
            "orders_by_user": OrdersByUserLoader()
        }
    }

Best Practices

REST-APIs

  1. Einheitliche Benennung: Verwende Plural-Nomen für Sammlungen (/users, nicht /user)
  2. Zustandslosigkeit: 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: Große Sammlungen immer paginieren
  6. Ratenbegrenzung: Schütze Deine API mit Ratenlimits
  7. Dokumentation: Verwende OpenAPI/Swagger für interaktive Dokumentation

GraphQL-APIs

  1. Schema zuerst: Entwirf das Schema, bevor Du Resolver schreibst
  2. N+1 vermeiden: Verwende DataLoaders für effizientes Datenabrufen
  3. Eingabevalidierung: Validiere auf Schema- und Resolver-Ebene
  4. Fehlerbehandlung: Gib strukturierte Fehler in Mutations-Payloads zurück
  5. Paginierung: Verwende cursor-basierte Paginierung (Relay-Spezifikation)
  6. Deprecation: Verwende die @deprecated-Direktive für schrittweise Migration
  7. Monitoring: Verfolge die Abfragekomplexität und Ausführungszeit

Häufige Fehler

  • Übermäßiges/Unterladen (REST): In GraphQL behoben, erfordert aber DataLoaders
  • Bahnbrechende Änderungen: Versioniere APIs oder verwende Deprecation-Strategien
  • Inkonsistente Fehlerformate: Standardisiere Fehlerantworten
  • Fehlende Ratenlimits: APIs ohne Limits sind angreifbar
  • 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 REST-API-Designleitfaden
  • 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 vor der Implementierung
  • scripts/openapi-generator.py: OpenAPI-Spezifikationen aus Code generieren

Individual skills in this repo

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

majiayu000/claude-skill-registry

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".

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

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

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

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

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

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

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

majiayu000/claude-skill-registry

BlockRun works with Claude Code and Google Antigravity.

majiayu000/claude-skill-registry

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

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

majiayu000/claude-skill-registry

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

CRITICAL: Use for MolyKit AI chat toolkit. Triggers on: BotClient, OpenAI, SSE streaming, AI chat, molykit, PlatformSend, spawn(), ThreadToken, cross-platform async, Chat widget, Messages, PromptInput, Avatar, LLM

majiayu000/claude-skill-registry

AI and machine learning workflow covering LLM application development, RAG implementation, agent architecture, ML pipelines, and AI-powered features.

majiayu000/claude-skill-registry

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

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

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

Verwandte Skills