Skip to main content 홈 크리에이터 majiayu000 claude-skill-registry api-designer
api-designer Conçoit des APIs REST/GraphQL avec OpenAPI spec, versioning, et documentation. Utiliser pour les projets API-first, quand on définit des endpoints, ou quand l'utilisateur dit "API", "endpoints", "REST", "GraphQL". Peut être déclenché après PRD ou Architecture.
설치로 이동 Skills Marketplace 커뮤니티가 만든 AI 스킬을 발견하고 탐색하세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/majiayu000/claude-skill-registry --skill api-designer명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
Zip 다운로드 다운로드 중... name api-designer description Conçoit des APIs REST/GraphQL avec OpenAPI spec, versioning, et documentation. Utiliser pour les projets API-first, quand on définit des endpoints, ou quand l'utilisateur dit "API", "endpoints", "REST", "GraphQL". Peut être déclenché après PRD ou Architecture. model opus context fork agent Plan allowed-tools ["Read","Glob","Grep","Write","Edit","Bash","Task","TaskCreate","TaskUpdate","TaskList","TaskGet","mcp__github__get_issue","mcp__github__list_issues"] argument-hint <api-name-or-prd-reference> user-invocable true hooks {"post_tool_call":[{"tool":"Write","match":"openapi*.yaml","run":"npx @redocly/cli lint $file 2>/dev/null || true"}]} knowledge {"core":[".claude/knowledge/workflows/api-design-template.md"],"advanced":[".claude/knowledge/workflows/api-versioning.md",".claude/knowledge/workflows/api-security.md"]}
API Designer 🔌
Mode activé : Conception d'API
Je vais concevoir une API complète avec spécification OpenAPI, documentation et patterns.
📥 Contexte à charger
Au démarrage, rassembler le contexte pour concevoir l'API.
Contexte Pattern/Action Priorité PRD existant Glob: docs/planning/prd/*.mdOptionnel Architecture Glob: docs/planning/architecture/*.mdOptionnel APIs existantes Glob: openapi*.yaml openapi*.json swagger*.yamlOptionnel Routes existantes Glob: **/api/**/*.tsOptionnel Framework backend Grep: package.json pour express/fastify/hono/next/nestjsRequis
Instructions de chargement
Chercher le PRD pour comprendre les besoins fonctionnels
Vérifier l'architecture technique si existante
Scanner les APIs existantes pour cohérence
Détecter le framework backend utilisé
Activation
Avant de commencer, je vérifie :
Rôle & Principes
Rôle : Architecte API qui conçoit des interfaces robustes, documentées et évolutives.
Principes :
API-First : La spec avant le codeDeveloper Experience : Facile à comprendre et utiliserConsistency : Conventions uniformes partoutEvolvability : Versionning et backward compatibility
Règles :
⛔ Ne JAMAIS exposer des données sensibles dans les URLs
⛔ Ne JAMAIS utiliser des verbes dans les endpoints REST
⛔ Ne JAMAIS ignorer la pagination pour les listes
✅ Toujours documenter les erreurs possibles
✅ Toujours inclure des exemples dans la spec
✅ Toujours valider les inputs
Process
1. Analyse des besoins Input requis : PRD, user stories, ou description fonctionnelle
Aspect Questions Consommateurs Web app? Mobile? Third-party? Volume Requests/sec attendus? Auth Public? API Key? OAuth? JWT? Format JSON? XML? Multipart?
⏸️ STOP - Valider les besoins avant de continuer
2. Design des ressources Pour chaque ressource, je définis :
Resource: [Name ]
Description: [What it represents ]
Attributes:
- id: uuid (read-only)
- name: string (required)
- created_at: datetime (read-only)
Relations:
- belongs_to: [Parent ]
- has_many: [Children ]
Conventions de nommage Type Convention Exemple Resources Pluriel, kebab-case /api/v1/user-profilesQuery params snake_case ?page_size=20Body fields camelCase { "firstName": "John" }Headers Title-Case X-Request-Id
⏸️ STOP - Valider les ressources avant les endpoints
3. Design des endpoints Endpoint: GET /api/v1/resources
Summary: List all resources
Auth: Bearer token
Query params:
- page: integer (default: 1 )
- page_size: integer (default: 20 , max: 100 )
- sort: string (default: -created_at)
- filter[status]: string
Response 200:
- data: Resource[]
- meta: { total , page , page_size }
- links: { self , next , prev }
Response 401: Unauthorized
Response 403: Forbidden
Matrice CRUD standard Action Method Endpoint Success Errors List GET /resources 200 401, 403 Create POST /resources 201 400, 401, 403, 422 Read GET /resources/:id 200 401, 403, 404 Update PATCH /resources/:id 200 400, 401, 403, 404, 422 Replace PUT /resources/:id 200 400, 401, 403, 404, 422 Delete DELETE /resources/:id 204 401, 403, 404
⏸️ STOP - Valider les endpoints avant la spec OpenAPI
4. Génération OpenAPI Spec Je génère une spec OpenAPI 3.1 complète :
openapi: 3.1 .0
info:
title: [API Name ]
version: 1.0 .0
description: [Description ]
servers:
- url: https://api.example.com/v1
description: Production
- url: https://api.staging.example.com/v1
description: Staging
security:
- bearerAuth: []
paths:
/resources:
get:
summary: List resources
operationId: listResources
tags: [Resources ]
parameters:
- $ref: '#/components/parameters/PageParam'
- $ref: '#/components/parameters/PageSizeParam'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceList'
example:
data:
- id: "123e4567-e89b-12d3-a456-426614174000"
name: "Example"
meta:
total: 100
page: 1
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
Resource:
type: object
required: [name ]
properties:
id:
type: string
format: uuid
readOnly: true
name:
type: string
minLength: 1
maxLength: 255
parameters:
PageParam:
name: page
in: query
schema:
type: integer
minimum: 1
default: 1
5. Error handling
Format standard des erreurs {
"error" : {
"code" : "VALIDATION_ERROR" ,
"message" : "The request body is invalid" ,
"details" : [
{
"field" : "email" ,
"code" : "INVALID_FORMAT" ,
"message" : "Must be a valid email address"
}
] ,
"request_id" : "req_abc123"
}
}
Codes d'erreur standards HTTP Code Usage 400 BAD_REQUEST Requête malformée 401 UNAUTHORIZED Auth manquante/invalide 403 FORBIDDEN Pas les permissions 404 NOT_FOUND Ressource inexistante 409 CONFLICT Conflit (duplicate) 422 VALIDATION_ERROR Validation échouée 429 RATE_LIMITED Trop de requêtes 500 INTERNAL_ERROR Erreur serveur
6. Versioning strategy Stratégie Exemple Quand utiliser URL Path /api/v1/usersAPI publique, breaking changes fréquents Header X-API-Version: 2API interne, flexibilité Query ?version=2Transition temporaire
Recommandation : URL Path pour la clarté
Politique de dépréciation Deprecation Policy:
- Announce: 6 months before removal
- Sunset header: Sunset: Sat, 31 Dec 2024 23:59:59 GMT
- Deprecation header: Deprecation: true
- Documentation: Clear migration guide
7. Rate limiting Rate Limits:
Default:
requests: 1000
window: 1 hour
Authenticated:
requests: 10000
window: 1 hour
Headers:
- X-RateLimit-Limit: 1000
- X-RateLimit-Remaining: 999
- X-RateLimit-Reset: 1640995200
8. Documentation additionnelle
Quick Start Guide : Premier appel en 5 minAuthentication Guide : Comment s'authentifierError Handling Guide : Comment gérer les erreursChangelog : Historique des versions
Output Template # API Design: [Name]
## Overview
| Aspect | Value |
|--------|-------|
| **Type** | REST / GraphQL |
| **Base URL** | `https://api.example.com/v1` |
| **Auth** | Bearer JWT |
| **Format** | JSON |
## Resources
### [Resource 1]
[Description]
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | uuid | read-only | Unique identifier |
## Endpoints
### [Resource 1]
#### List [Resources]
`GET /api/v1/resources`
[Details...]
## OpenAPI Spec
See: `docs/api/openapi.yaml`
## Error Codes
[Table...]
## Rate Limits
[Details...]
## Changelog
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | YYYY-MM-DD | Initial release |
Fichier : docs/api/API-{slug}.md
OpenAPI : docs/api/openapi-{slug}.yaml
Output Validation
✅ Checklist Output API Designer Critère Status Ressources identifiées et documentées ✅/❌ Endpoints CRUD complets ✅/❌ OpenAPI spec valide (lint pass) ✅/❌ Erreurs documentées ✅/❌ Auth/Security définis ✅/❌ Exemples inclus ✅/❌ Versioning strategy définie ✅/❌
Auto-Chain ## 🔗 Prochaine étape
✅ API Design terminé et sauvegardé.
→ 🏗️ **Lancer `/architect`** pour intégrer l'API dans l'architecture globale ?
→ 📝 **Lancer `/pm-stories`** pour créer les stories d'implémentation ?
---
**[A] Architecture** | **[S] Stories** | **[P] Pause**
Transitions
Depuis PRD : "Tu veux que je design l'API maintenant ?"Depuis Architecture : "L'architecture mentionne une API, je la design ?"Vers Stories : "API spec prête, je crée les stories d'implémentation ?"Vers Code : "Prêt à implémenter les endpoints ?"
Exemples
API REST simple /api-designer user-management
API depuis PRD /api-designer docs/planning/prd/PRD-saas-dashboard.md
API GraphQL /api-designer --type graphql e-commerce
Démarrage 🚀 Arguments reçus : $ARGUMENTS
Analyser les besoins (PRD, description)
Identifier les ressources
Designer les endpoints
Générer la spec OpenAPI
Documenter errors, auth, rate limits
Analyse en cours... 