Communitygithub.com

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 raviront les développeurs.

Qu'est-ce que Principes de Conception d'API ?

Cette compétence fournit un guide complet sur les principes de conception d'API REST et GraphQL, destiné aux développeurs et aux architectes. Elle explique comment construire des API intuitives, évolutives et maintenables, en se concentrant sur des architectures orientées ressources pour REST et le développement schema-first pour GraphQL. La compétence inclut des modèles de conception pratiques (pagination, gestion des erreurs, HATEOAS, DataLoader), des extraits de code Python et GraphQL, ainsi que des stratégies de versioning. Elle est utile pour concevoir de nouvelles API, refactorer des API existantes, établir des normes de conception et examiner des spécifications. Les plateformes supportées incluent FastAPI (REST) et Ariadne (GraphQL), avec des templates et des listes de contrôle disponibles dans des ressources associées.

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

Demander à votre IA préférée

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

Documentation

Que fait Principes de Conception d'API ?

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

Quand utiliser cette compétence

  • Concevoir de nouvelles API REST ou GraphQL
  • Refactorer des API existantes pour une meilleure utilisabilité
  • Établir des normes de conception d'API pour votre équipe
  • Examiner les spécifications d'API avant leur implémentation
  • Migrer entre les paradigmes d'API (REST vers GraphQL, etc.)
  • Créer une documentation d'API adaptée aux développeurs
  • Optimiser les API pour des cas d'utilisation spécifiques (mobile, intégrations tierces)

Concepts Fondamentaux

1. Principes de Conception REST

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 Schema-First

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

Structure de Requête :

  • Les clients demandent exactement ce dont ils ont besoin
  • Un seul point de terminaison, plusieurs opérations
  • Schéma fortement typé
  • Introspection intégrée

3. Stratégies de Versioning d'API

Versioning par URL :

/api/v1/utilisateurs
/api/v2/utilisateurs

Versioning par En-tête :

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

Versioning par Paramètre de Requête :

/api/utilisateurs?version=1

Modèles de Conception REST

Modèle 1 : Conception de Collection de Ressources

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

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

# Mauvais : Points de terminaison orientés actions (à éviter)
POST   /api/creerUtilisateur
POST   /api/obtenirUtilisateurParId
POST   /api/supprimerUtilisateur

Modèle 2 : Pagination et Filtrage

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

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

class ParametresFiltre(BaseModel):
    statut: Optional[str] = None
    cree_apres: Optional[str] = None
    recherche: Optional[str] = None

class ReponsePaginee(BaseModel):
    elements: List[dict]
    total: int
    page: int
    taille_page: int
    pages: int

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

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

# Exemple de point de terminaison FastAPI
from fastapi import FastAPI, Query, Depends

app = FastAPI()

@app.get("/api/utilisateurs", response_model=ReponsePaginee)
async def lister_utilisateurs(
    page: int = Query(1, ge=1),
    taille_page: int = Query(20, ge=1, le=100),
    statut: Optional[str] = Query(None),
    recherche: Optional[str] = Query(None)
):
    # Appliquer les filtres
    requete = construire_requete(statut=statut, recherche=recherche)

    # Compter le total
    total = await compter_utilisateurs(requete)

    # Récupérer la page
    offset = (page - 1) * taille_page
    utilisateurs = await recuperer_utilisateurs(requete, limite=taille_page, offset=offset)

    return ReponsePaginee(
        elements=utilisateurs,
        total=total,
        page=page,
        taille_page=taille_page,
        pages=(total + taille_page - 1) // taille_page
    )

Modèle 3 : Gestion des Erreurs et Codes de Statut

from fastapi import HTTPException, status
from pydantic import BaseModel

class ReponseErreur(BaseModel):
    erreur: str
    message: str
    details: Optional[dict] = None
    horodatage: str
    chemin: str

class DetailErreurValidation(BaseModel):
    champ: str
    message: str
    valeur: Any

# Réponses d'erreur cohérentes
CODES_STATUT = {
    "succes": 200,
    "cree": 201,
    "aucun_contenu": 204,
    "mauvaise_requete": 400,
    "non_autorise": 401,
    "interdit": 403,
    "non_trouve": 404,
    "conflit": 409,
    "non_traitable": 422,
    "erreur_interne": 500
}

def lever_non_trouve(ressource: str, id: str):
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail={
            "error": "NonTrouve",
            "message": f"{ressource} introuvable",
            "details": {"id": id}
        }
    )

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

# Exemple d'utilisation
@app.get("/api/utilisateurs/{utilisateur_id}")
async def obtenir_utilisateur(utilisateur_id: str):
    utilisateur = await recuperer_utilisateur(utilisateur_id)
    if not utilisateur:
        lever_non_trouve("Utilisateur", utilisateur_id)
    return utilisateur

Modèle 4 : HATEOAS (Hypermedia as the Engine of Application State)

class ReponseUtilisateur(BaseModel):
    id: str
    nom: str
    email: str
    _liens: dict

    @classmethod
    def depuis_utilisateur(cls, utilisateur: User, url_base: str):
        return cls(
            id=utilisateur.id,
            nom=utilisateur.nom,
            email=utilisateur.email,
            _liens={
                "self": {"href": f"{url_base}/api/utilisateurs/{utilisateur.id}"},
                "commandes": {"href": f"{url_base}/api/utilisateurs/{utilisateur.id}/commandes"},
                "mettre_a_jour": {
                    "href": f"{url_base}/api/utilisateurs/{utilisateur.id}",
                    "method": "PATCH"
                },
                "supprimer": {
                    "href": f"{url_base}/api/utilisateurs/{utilisateur.id}",
                    "method": "DELETE"
                }
            }
        )

Modèles de Conception GraphQL

Modèle 1 : Conception de Schéma

# schema.graphql

# Définitions de types claires
type Utilisateur {
  id: ID!
  email: String!
  nom: String!
  creeLe: DateTime!

  # Relations
  commandes(premier: Int = 20, apres: String, statut: StatutCommande): ConnexionCommande!

  profil: ProfilUtilisateur
}

type Commande {
  id: ID!
  statut: StatutCommande!
  total: Monnaie!
  articles: [ArticleCommande!]!
  creeLe: DateTime!

  # Référence arrière
  utilisateur: Utilisateur!
}

# Modèle de pagination (style Relay)
type ConnexionCommande {
  aretes: [AreteCommande!]!
  infosPage: InfosPage!
  totalCount: Int!
}

type AreteCommande {
  noeud: Commande!
  curseur: String!
}

type InfosPage {
  aPageSuivante: Boolean!
  aPagePrecedente: Boolean!
  curseurDebut: String
  curseurFin: String
}

# Énumérations pour la sécurité des types
enum StatutCommande {
  EN_ATTENTE
  CONFIRMEE
  EXPEDIEE
  LIVREE
  ANNULEE
}

# Scalaires personnalisés
scalar DateTime
scalar Monnaie

# Racine de requête
type Query {
  utilisateur(id: ID!): Utilisateur
  utilisateurs(premier: Int = 20, apres: String, recherche: String): ConnexionUtilisateur!

  commande(id: ID!): Commande
}

# Racine de mutation
type Mutation {
  creerUtilisateur(entree: EntreeCreerUtilisateur!): PayloadCreerUtilisateur!
  mettreAJourUtilisateur(entree: EntreeMettreAJourUtilisateur!): PayloadMettreAJourUtilisateur!
  supprimerUtilisateur(id: ID!): PayloadSupprimerUtilisateur!

  creerCommande(entree: EntreeCreerCommande!): PayloadCreerCommande!
}

# Types d'entrée pour les mutations
input EntreeCreerUtilisateur {
  email: String!
  nom: String!
  motDePasse: String!
}

# Types de payload pour les mutations
type PayloadCreerUtilisateur {
  utilisateur: Utilisateur
  erreurs: [Erreur!]
}

type Erreur {
  champ: String
  message: String!
}

Modèle 2 : Conception de Résolveur

from typing import Optional, List
from ariadne import QueryType, MutationType, ObjectType
from dataclasses import dataclass

requete = QueryType()
mutation = MutationType()
type_utilisateur = ObjectType("Utilisateur")

@requete.field("utilisateur")
async def resoudre_utilisateur(obj, info, id: str) -> Optional[dict]:
    """Résout un seul utilisateur par ID."""
    return await recuperer_utilisateur_par_id(id)

@requete.field("utilisateurs")
async def resoudre_utilisateurs(
    obj,
    info,
    premier: int = 20,
    apres: Optional[str] = None,
    recherche: Optional[str] = None
) -> dict:
    """Résout une liste paginée d'utilisateurs."""
    # Décoder le curseur
    decalage = decoder_curseur(apres) if apres else 0

    # Récupérer les utilisateurs
    utilisateurs = await recuperer_utilisateurs(
        limite=premier + 1,  # En récupérer un de plus pour vérifier aPageSuivante
        decalage=decalage,
        recherche=recherche
    )

    # Pagination
    a_suivant = len(utilisateurs) > premier
    if a_suivant:
        utilisateurs = utilisateurs[:premier]

    aretes = [
        {
            "noeud": utilisateur,
            "curseur": encoder_curseur(decalage + i)
        }
        for i, utilisateur in enumerate(utilisateurs)
    ]

    return {
        "edges": aretes,
        "pageInfo": {
            "hasNextPage": a_suivant,
            "hasPreviousPage": decalage > 0,
            "startCursor": aretes[0]["curseur"] if aretes else None,
            "endCursor": aretes[-1]["curseur"] if aretes else None
        },
        "totalCount": await compter_utilisateurs(recherche=recherche)
    }

@type_utilisateur.field("commandes")
async def resoudre_commandes_utilisateur(utilisateur: dict, info, premier: int = 20) -> dict:
    """Résout les commandes d'un utilisateur (prévention N+1 avec DataLoader)."""
    # Utiliser DataLoader pour regrouper les requêtes
    chargeur = info.context["chargeurs"]["commandes_par_utilisateur"]
    commandes = await chargeur.load(utilisateur["id"])

    return paginer_commandes(commandes, premier)

@mutation.field("creerUtilisateur")
async def resoudre_creer_utilisateur(obj, info, entree: dict) -> dict:
    """Crée un nouvel utilisateur."""
    try:
        # Valider l'entrée
        valider_entree_utilisateur(entree)

        # Créer l'utilisateur
        utilisateur = await creer_utilisateur(
            email=entree["email"],
            nom=entree["nom"],
            motDePasse=hacher_mot_de_passe(entree["motDePasse"])
        )

        return {
            "utilisateur": utilisateur,
            "erreurs": []
        }
    except ErreurValidation as e:
        return {
            "utilisateur": None,
            "erreurs": [{"champ": e.champ, "message": e.message}]
        }

Modèle 3 : DataLoader (Prévention du Problème N+1)

from aiodataloader import DataLoader
from typing import List, Optional

class ChargeurUtilisateur(DataLoader):
    """Charge les utilisateurs par lots par ID."""

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

        # Mapper les résultats à l'ordre d'entrée
        map_utilisateurs = {utilisateur["id"]: utilisateur for utilisateur in utilisateurs}
        return [map_utilisateurs.get(id_utilisateur) for id_utilisateur in ids_utilisateurs]

class ChargeurCommandesParUtilisateur(DataLoader):
    """Charge les commandes par lots par ID d'utilisateur."""

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

        # Grouper les commandes par utilisateur_id
        commandes_par_utilisateur = {}
        for commande in commandes:
            id_utilisateur = commande["utilisateur_id"]
            if id_utilisateur not in commandes_par_utilisateur:
                commandes_par_utilisateur[id_utilisateur] = []
            commandes_par_utilisateur[id_utilisateur].append(commande)

        # Retourner dans l'ordre d'entrée
        return [commandes_par_utilisateur.get(id_utilisateur, []) for id_utilisateur in ids_utilisateurs]

# Configuration du contexte
def creer_contexte():
    return {
        "chargeurs": {
            "utilisateur": ChargeurUtilisateur(),
            "commandes_par_utilisateur": ChargeurCommandesParUtilisateur()
        }
    }

Bonnes Pratiques

API REST

  1. Nommage Cohérent : Utilisez des noms au pluriel pour les collections (/utilisateurs, pas /utilisateur)
  2. Sans État : Chaque requête contient toutes les informations nécessaires
  3. Utilisez Correctement les Codes de Statut HTTP : 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. Schema d'Abord : Concevez le schéma avant d'écrire les résolveurs
  2. Évitez N+1 : Utilisez DataLoaders pour une récupération de données efficace
  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 payloads de mutation
  5. Pagination : Utilisez la pagination basée sur les curseurs (spécification Relay)
  6. Dépréciation : 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

  • Surcharge/Sous-charge (REST) : Résolu dans GraphQL mais nécessite des DataLoaders
  • Changements Cassants : Versionnez les API ou utilisez des stratégies de dépréciation
  • Formats d'Erreur Incohérents : Standardisez les réponses d'erreur
  • Limites de Débit Manquantes : Les API sans limites sont vulnérables aux abus
  • Mauvaise Documentation : 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 : Modèles et anti-modèles de schéma GraphQL
  • references/api-versioning-strategies.md : Approches de versionnage et chemins de migration
  • assets/rest-api-template.py : Modèle d'API REST FastAPI
  • assets/graphql-schema-template.graphql : Exemple complet de schéma GraphQL
  • assets/api-design-checklist.md : Liste de contrôle de pré-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

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.

Skills associés