designing-apis

npx skills add majiayu000/claude-skill-registry --skill designing-apis-cloudai-x-opencode-workflow --agent claude-code

Same command for any agent — swap --agent for codex, cursor, copilot.

# Designing APIs Principles and patterns for designing clean, consistent, and maintainable APIs. ## When to Use This Skill - Designing new API endpoints - Reviewing API contracts - Planning API versioning strategies - Defining request/response schemas - Building GraphQL schemas - Documenting APIs --- ## REST API Design Principles ### Resource-Oriented Design APIs should be organized around **resources**, not actions: ``` GOOD (Resource-oriented): GET /users → List users GET /users/123 → Get user 123 POST /users → Create user PUT /users/123 → Update user 123 DELETE /users/123 → Delete user 123 BAD (Action-oriented): POST /getUsers POST /createUser POST /updateUser POST /deleteUser ``` ### HTTP Method Semantics | Method | Purpose | Idempotent | Safe | Request Body | |--------|---------|------------|------|--------------| | GET | Retrieve resource(s) | Yes | Yes | No | | POST | Create resource | No | No | Yes | | PUT | Replace resource | Yes | No | Yes | | PATCH | Partial update | Yes | No | Yes | | DELETE | Remove resource | Yes | No | Optional | ### URL Structure Patterns ``` Collection: /users Item: /users/{id} Nested: /users/{id}/posts Action: /users/{id}/activate (POST only, for