Communitygithub.com

API Design Principles (Principes de conception d'API)

Maîtrisez les principes de conception d'API REST et GraphQL pour créer des API intuitives, évolutives et maintenables qui ravissent les développeurs. À utiliser lors de la conception de nouvelles API, de la révision de spécifications ou de l'établissement de normes de conception.

Qu'est-ce que API Design Principles (Principes de conception d'API) ?

Cette compétence fournit un guide complet sur la conception d'API REST et GraphQL, en mettant l'accent sur la création d'API intuitives, évolutives et maintenables. Elle couvre les principes fondamentaux de la conception orientée ressource REST, la sémantique des méthodes HTTP, et l'approche schema-first de GraphQL avec ses types de requêtes, mutations et abonnements. La compétence détaille des stratégies de versionnement (URL, en-tête, paramètre de requête) et propose des patrons de conception concrets pour la gestion des collections, la pagination, le filtrage, la gestion des erreurs avec codes de statut HTTP standardisés, et l'implémentation HATEOAS pour la découvrabilité des API. Côté GraphQL, elle présente la conception de schémas typés (types, énumérations, scalaires personnalisés), la mise en œuvre de résolveurs avec pagination par curseur (Relay-style), et la prévention du problème N+1 via l'utilisation de DataLoaders pour un chargement efficace des données. Idéale pour les développeurs utilisant des frameworks comme FastAPI, Ariadne, ou tout autre langage, cette compétence est utile lors de la conception d'API, la révision de spécifications, la migration entre paradigmes, ou l'établissement de normes d'équipe. Elle inclut des extraits de code Python (FastAPI) et des exemples de schémas GraphQL, ainsi que des ressources de référence pour approfondir.

Compatible avec✓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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Principes de conception d'API

Maîtrisez les principes de conception d'API REST et GraphQL pour créer des API intuitives, évolutives et maintenables qui ravissent les développeurs et résistent à l'épreuve du temps.

Quand utiliser cette compétence

  • Conception de nouvelles API REST ou GraphQL
  • Refactorisation d'API existantes pour une meilleure utilisabilité
  • Établissement de normes de conception d'API pour votre équipe
  • Révision des spécifications d'API avant implémentation
  • Migration entre paradigmes d'API (REST vers GraphQL, etc.)
  • Création de documentation d'API conviviale pour les développeurs
  • Optimisation d'API pour des cas d'utilisation spécifiques (mobile, intégrations tierces)

Concepts fondamentaux

1. Principes de conception RESTful

Architecture orientée ressource

  • Les ressources sont des noms (utilisateurs, commandes, produits), pas des verbes
  • Utilisez les méthodes HTTP pour les actions (GET, POST, PUT, PATCH, DELETE)
  • Les URL représentent des hiérarchies de ressources
  • Conventions de nommage cohérentes

Sémantique des méthodes HTTP :

  • GET : Récupérer des ressources (idempotent, sûr)
  • POST : Créer de nouvelles ressources
  • PUT : Remplacer entièrement une ressource (idempotent)
  • PATCH : Mises à jour partielles de ressources
  • DELETE : Supprimer des ressources (idempotent)

2. Principes de conception GraphQL

Développement centré sur le schéma

  • Les types définissent votre modèle de domaine
  • Les requêtes pour lire les données
  • Les mutations pour modifier les données
  • Les abonnements pour les mises à jour en temps réel

Structure de requête :

  • Les clients demandent exactement ce dont ils ont besoin
  • Point de terminaison unique, opérations multiples
  • Schéma fortement typé
  • Introspection intégrée

3. Stratégies de versionnement d'API

Versionnement par URL :

/api/v1/users
/api/v2/users

Versionnement par en-tête :

Accept: application/vnd.api+json; version=1

Versionnement par paramètre de requête :

/api/users?version=1

Patrons de conception d'API REST

Patron 1 : Conception de collections de ressources

# Bon : Points de terminaison orientés ressources
GET    /api/users              # Lister les utilisateurs (avec pagination)
POST   /api/users              # Créer un utilisateur
GET    /api/users/{id}         # Obtenir un utilisateur spécifique
PUT    /api/users/{id}         # Remplacer un utilisateur
PATCH  /api/users/{id}         # Mettre à jour les champs d'un utilisateur
DELETE /api/users/{id}         # Supprimer un utilisateur

# Ressources imbriquées
GET    /api/users/{id}/orders  # Obtenir les commandes d'un utilisateur
POST   /api/users/{id}/orders  # Créer une commande pour un utilisateur

# Mauvais : Points de terminaison orientés actions (à éviter)
POST   /api/createUser
POST   /api/getUserById
POST   /api/deleteUser

Patron 2 : Pagination et filtrage

from typing import List, Optional
from pydantic import BaseModel, Field

class PaginationParams(BaseModel):
    page: int = Field(1, ge=1, description="Numéro de page")
    page_size: int = Field(20, ge=1, le=100, description="Éléments par page")

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

# Exemple de point de terminaison FastAPI
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)
):
    # Appliquer les filtres
    query = build_query(status=status, search=search)

    # Compter le total
    total = await count_users(query)

    # Récupérer la page
    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
    )

Patron 3 : Gestion des erreurs et codes de statut

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

# Réponses d'erreur cohérentes
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} introuvable",
            "details": {"id": id}
        }
    )

def raise_validation_error(errors: List[ValidationErrorDetail]):
    raise HTTPException(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        detail={
            "error": "ValidationError",
            "message": "La validation de la requête a échoué",
            "details": {"errors": [e.dict() for e in errors]}
        }
    )

# Exemple d'utilisation
@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("Utilisateur", user_id)
    return user

Patron 4 : HATEOAS (Hypermedia comme moteur de l'état de l'application)

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"
                }
            }
        )

Patrons de conception GraphQL

Patron 1 : Conception de schéma

# schema.graphql

# Définitions de types claires
type User {
  id: ID!
  email: String!
  name: String!
  createdAt: DateTime!

  # Relations
  orders(first: Int = 20, after: String, status: OrderStatus): OrderConnection!

  profile: UserProfile
}

type Order {
  id: ID!
  status: OrderStatus!
  total: Money!
  items: [OrderItem!]!
  createdAt: DateTime!

  # Référence inverse
  user: User!
}

# Patron de pagination (style Relay)
type OrderConnection {
  edges: [OrderEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type OrderEdge {
  node: Order!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

# Énumérations pour la sécurité de type
enum OrderStatus {
  PENDING
  CONFIRMED
  SHIPPED
  DELIVERED
  CANCELLED
}

# Scalaires personnalisés
scalar DateTime
scalar Money

# Racine des requêtes
type Query {
  user(id: ID!): User
  users(first: Int = 20, after: String, search: String): UserConnection!

  order(id: ID!): Order
}

# Racine des mutations
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(input: UpdateUserInput!): UpdateUserPayload!
  deleteUser(id: ID!): DeleteUserPayload!

  createOrder(input: CreateOrderInput!): CreateOrderPayload!
}

# Types d'entrée pour les mutations
input CreateUserInput {
  email: String!
  name: String!
  password: String!
}

# Types de charge utile pour les mutations
type CreateUserPayload {
  user: User
  errors: [Error!]
}

type Error {
  field: String
  message: String!
}

Patron 2 : Conception de résolveurs

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]:
    """Résout un seul utilisateur par ID."""
    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:
    """Résout une liste paginée d'utilisateurs."""
    # Décoder le curseur
    offset = decode_cursor(after) if after else 0

    # Récupérer les utilisateurs
    users = await fetch_users(
        limit=first + 1,  # En récupérer un de plus pour vérifier hasNextPage
        offset=offset,
        search=search
    )

    # Pagination
    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:
    """Résout les commandes d'un utilisateur (prévention N+1 avec DataLoader)."""
    # Utiliser DataLoader pour regrouper les requêtes
    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:
    """Crée un nouvel utilisateur."""
    try:
        # Valider l'entrée
        validate_user_input(input)

        # Créer l'utilisateur
        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}]
        }

Patron 3 : DataLoader (prévention du problème N+1)

from aiodataloader import DataLoader
from typing import List, Optional

class UserLoader(DataLoader):
    """Charge les utilisateurs par ID en lot."""

    async def batch_load_fn(self, user_ids: List[str]) -> List[Optional[dict]]:
        """Charge plusieurs utilisateurs en une seule requête."""
        users = await fetch_users_by_ids(user_ids)

        # Mapper les résultats à l'ordre d'entrée
        user_map = {user["id"]: user for user in users}
        return [user_map.get(user_id) for user_id in user_ids]

class OrdersByUserLoader(DataLoader):
    """Charge les commandes par ID d'utilisateur en lot."""

    async def batch_load_fn(self, user_ids: List[str]) -> List[List[dict]]:
        """Charge les commandes pour plusieurs utilisateurs en une seule requête."""
        orders = await fetch_orders_by_user_ids(user_ids)

        # Grouper les commandes par user_id
        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)

        # Retourner dans l'ordre d'entrée
        return [orders_by_user.get(user_id, []) for user_id in user_ids]

# Configuration du contexte
def create_context():
    return {
        "loaders": {
            "user": UserLoader(),
            "orders_by_user": OrdersByUserLoader()
        }
    }

Bonnes pratiques

API REST

  1. Nommage cohérent : Utilisez des noms au pluriel pour les collections (/users, pas /user)
  2. Sans état : Chaque requête contient toutes les informations nécessaires
  3. Utilisez les codes de statut HTTP correctement : 2xx succès, 4xx erreurs client, 5xx erreurs serveur
  4. Versionnez votre API : Planifiez les changements cassants dès le premier jour
  5. Pagination : Paginez toujours les grandes collections
  6. Limitation de débit : Protégez votre API avec des limites de débit
  7. Documentation : Utilisez OpenAPI/Swagger pour une documentation interactive

API GraphQL

  1. Schéma d'abord : Concevez le schéma avant d'écrire les résolveurs
  2. Évitez le N+1 : Utilisez DataLoaders pour une récupération efficace des données
  3. Validation des entrées : Validez au niveau du schéma et des résolveurs
  4. Gestion des erreurs : Retournez des erreurs structurées dans les charges utiles des mutations
  5. Pagination : Utilisez la pagination basée sur les curseurs (spécification Relay)
  6. Obsolescence : Utilisez la directive @deprecated pour une migration progressive
  7. Surveillance : Suivez la complexité des requêtes et le temps d'exécution

Pièges courants

  • Sur-récupération / Sous-récupération (REST) : Résolu dans GraphQL mais nécessite DataLoaders
  • Changements cassants : Versionnez les API ou utilisez des stratégies d'obsolescence
  • Formats d'erreur incohérents : Standardisez les réponses d'erreur
  • Absence de limites de débit : Les API sans limites sont vulnérables aux abus
  • Documentation de qualité médiocre : Les API non documentées frustrent les développeurs
  • Ignorer la sémantique HTTP : POST pour des opérations idempotentes brise les attentes
  • Couplage fort : La structure de l'API ne doit pas refléter le schéma de la base de données

Ressources

  • references/rest-best-practices.md : Guide complet de conception d'API REST
  • references/graphql-schema-design.md : Patrons et anti-patrons de schémas GraphQL
  • references/api-versioning-strategies.md : Approches de versionnement et chemins de migration
  • assets/rest-api-template.py : Modèle d'API REST FastAPI
  • assets/graphql-schema-template.graphql : Exemple de schéma GraphQL complet
  • assets/api-design-checklist.md : Liste de vérification de révision avant implémentation
  • scripts/openapi-generator.py : Générer des spécifications OpenAPI à partir du 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".

Skills associés