api-designlisted

# API Design Skill ## Purpose Standards and best practices for designing RESTful APIs. ## Auto-Invoke Triggers - Designing new API endpoints - Creating OpenAPI documentation - Implementing API versioning - Designing error responses - Implementing pagination --- ## REST API Principles ### Resource Naming - Use **nouns**, not verbs: `/users` not `/getUsers` - Use **plural** nouns: `/users` not `/user` - Use **kebab-case**: `/user-profiles` not `/userProfiles` - Use **lowercase** only - Max **2 levels** nesting: `/users/{id}/posts` ### URL Patterns | Pattern | Example | Use Case | |---------|---------|----------| | Collection | `/users` | List resources | | Item | `/users/{id}` | Single resource | | Nested | `/users/{id}/posts` | Related resources | | Action | `/users/{id}/activate` | Non-CRUD operations | --- ## HTTP Methods | Method | Purpose | Idempotent | Safe | Has Body | |--------|---------|------------|------|----------| | GET | Read | Yes | Yes | No | | POST | Create | No | No | Yes | | PUT | Replace entire resource | Yes | No | Yes | | PATCH | Partial update | No | No | Yes | | DELETE | Remove | Yes | No | No | ### Method Selection Rules - GET for retrieval only, never modify state - POST for creation, returns 201 with Location header - PUT replaces entire resource, all fields required - PATCH for partial updates, only changed fields - DELETE returns 204 No Content on success --- ## Status Codes ### Success (2xx) | Code | Use Case | |------|----------| | 2