api-design
Concevoir des API REST avec les meilleures pratiques
也可從以下取得: supercent-io
Les API souffrent souvent d'une incohérence dans les noms, d'une mauvaise structure d'URL et d'une utilisation incorrecte des méthodes HTTP. Cette compétence fournit des directives claires pour concevoir des API intuitives, évolutives et faciles à maintenir.
下載技能 ZIP
在 Claude 中上傳
前往 設定 → 功能 → 技能 → 上傳技能
開啟並開始使用
測試它
正在使用「api-design」。 Design a REST endpoint to create and retrieve orders
預期結果:
- POST /orders - Create a new order (returns 201 Created with Location header)
- GET /orders?status=pending&sort=-createdAt - List orders with filtering and sorting
- GET /orders/{id} - Retrieve a specific order (returns 404 if not found)
- All responses use envelope format with 'data' and 'meta' fields
正在使用「api-design」。 How should I structure error responses for validation failures?
預期結果:
- Use 400 Bad Request with error code VALIDATION_ERROR
- Include details array with field-specific messages
- Example: { error: { code: 'VALIDATION_ERROR', message: 'Invalid input', details: [{ field: 'email', message: 'Must be valid email' }] } }
安全審計
安全This is a documentation-only skill containing REST API design guidelines. All 99 static findings are false positives triggered by documentation examples being misinterpreted as executable code. No executable code, network calls, file system access, or external commands exist in this skill.
風險因素
🌐 網路存取 (1)
⚙️ 外部命令 (41)
🔑 環境變數 (1)
品質評分
你能建構什麼
Concevoir de nouvelles API REST
Appliquer les meilleures pratiques lors de la conception de nouveaux points de terminaison REST pour garantir la cohérence et la facilité d'utilisation.
Réviser les API existantes
Valider les conceptions d'API actuelles par rapport aux normes de l'industrie et identifier les domaines d'amélioration.
Créer des guides de style d'API
Établir des conventions d'équipe pour les noms d'URL, les formats de réponse et la gestion des erreurs.
試試這些提示
Concevez un point de terminaison REST pour la gestion des utilisateurs. Incluez la structure d'URL, la méthode HTTP, le format du corps de requête, le format de réponse et les codes d'état appropriés.
Quelle est la bonne façon de structurer les réponses d'erreur dans une API REST ? Montrez des exemples pour les erreurs de validation, les échecs d'authentification et les scénarios non trouvés.
Concevez une API REST pour les collections paginées. Montrez les approches de pagination basée sur le décalage et basée sur le curseur avec des exemples de requête et de réponse.
Quelles sont les meilleures pratiques pour le versionnage d'API ? Comparez le versionnage par chemin d'URL et le versionnage basé sur les en-têtes. Quand chaque approche devrait-elle être utilisée ?
最佳實務
- Utilisez des substantifs pluriels pour les URL de ressources (par exemple, /users et non /user)
- Appliquez correctement les méthodes HTTP : GET pour les lectures, POST pour les créations, PUT pour les remplacements, PATCH pour les mises à jour partielles, DELETE pour les suppressions
- Structurez les réponses de manière cohérente avec un format d'en-tête incluant des métadonnées pour les collections
避免
- Évitez les verbes dans les URL (par exemple, /getUsers, /createOrder) - la méthode HTTP transmet l'action
- N'utilisez pas de conventions de nommage incohérentes comme melanger snake_case et camelCase dans la même API
- Évitez l'imbrication profonde au-delà de deux niveaux - aplanissez les hiérarchies de ressources lorsque possible