api-design-principles
Concevoir des API intuitives et évolutives
Également disponible depuis: wshobson
Construire des API sans principes de conception cohérents conduit à des interfaces confuses et une mauvaise expérience développeur. Cette compétence fournit des modèles REST et GraphQL éprouvés pour créer des API maintenables, bien documentées et évolutives.
Télécharger le ZIP du skill
Importer dans Claude
Allez dans Paramètres → Capacités → Skills → Importer un skill
Activez et commencez à utiliser
Tester
Utilisation de "api-design-principles". Design endpoints for an e-commerce product catalog
Résultat attendu:
- GET /api/v1/products - List products with pagination
- GET /api/v1/products/{id} - Get product details
- POST /api/v1/products - Create product (admin only)
- PUT /api/v1/products/{id} - Replace product (admin only)
- PATCH /api/v1/products/{id} - Update product fields (admin only)
- DELETE /api/v1/products/{id} - Remove product (admin only)
- GET /api/v1/products/{id}/reviews - List product reviews
- GET /api/v1/categories/{id}/products - List products by category
Utilisation de "api-design-principles". What HTTP status codes for common scenarios?
Résultat attendu:
- 200 OK - Successful GET, PUT, PATCH requests
- 201 Created - Successful POST with resource creation
- 204 No Content - Successful DELETE or empty response
- 400 Bad Request - Malformed JSON or invalid syntax
- 401 Unauthorized - Missing or expired authentication
- 403 Forbidden - Valid auth but insufficient permissions
- 404 Not Found - Resource does not exist
- 409 Conflict - Resource conflict (e.g., duplicate key)
- 422 Unprocessable Entity - Validation errors
- 429 Too Many Requests - Rate limit exceeded
- 500 Internal Server Error - Unexpected server failure
Audit de sécurité
SûrStatic analysis flagged 201 patterns that are all false positives. The skill contains only documentation and educational content about API design. Markdown code blocks (backticks) were incorrectly identified as shell execution. Cryptographic references appear in security checklists, not actual implementations. URL and IP references are documentation examples for API endpoints. No executable code or security risks present.
Score de qualité
Ce que vous pouvez construire
Conception d'API Greenfield
Concevoir une nouvelle API REST ou GraphQL à partir de zéro avec une modélisation appropriée des ressources, une structure de points de terminaison et des normes de documentation avant le début de l'implémentation.
Révision et refactorisation d'API
Évaluer les points de terminaison d'API existants par rapport aux principes de conception pour identifier les incohérences, améliorer les conventions de nommage et planifier les stratégies de migration.
Documentation des standards d'équipe
Établir des directives de conception d'API à l'échelle de l'organisation couvrant le versionnage, la gestion des erreurs, les modèles d'authentification et les formats de réponse pour l'alignement de l'équipe.
Essayez ces prompts
J'ai besoin de concevoir des points de terminaison REST pour un système de blog avec des auteurs, des articles et des commentaires. Aidez-moi à structurer la hiérarchie des URL, les méthodes HTTP et les formats de réponse selon les meilleures pratiques REST.
Révisez mon schéma GraphQL pour un système de gestion d'utilisateurs. Vérifiez l'utilisation appropriée des types non-null, les implémentations d'interfaces et suggérez des améliorations pour l'efficacité des requêtes et éviter les problèmes N+1.
Mon API va avoir des changements cassants. Comparez le versionnage par chemin URL, le versionnage par en-tête et les approches par paramètre de requête pour mon cas d'utilisation. Incluez des recommandations de calendrier de dépréciation.
Concevez un format de réponse d'erreur cohérent pour mon API REST. Incluez les erreurs de validation au niveau des champs, les codes d'erreur pour le traitement programmatique et les codes d'état HTTP appropriés pour les scénarios courants.
Bonnes pratiques
- Utilisez des noms au pluriel pour les collections de ressources et gardez les hiérarchies d'URL peu profondes (maximum 2-3 niveaux d'imbrication)
- Implémentez une pagination cohérente avec des limites de taille de page documentées et incluez les métadonnées de nombre total dans les réponses
- Versionnez les API dès le début en utilisant le chemin URL ou le versionnage par en-tête, et maintenez une politique de dépréciation claire pour les anciennes versions
Éviter
- Utiliser des verbes dans les points de terminaison comme /createUser ou /getUserById au lieu des méthodes HTTP appropriées sur des noms de ressources
- Retourner des formats de réponse ou des noms de champs différents sur des points de terminaison similaires, cassant les attentes des clients
- Des URL profondément imbriquées comme /users/{id}/orders/{orderId}/items/{itemId}/reviews qui couplent les ressources trop strictement