api-designlisted

# API Design Skill > Design APIs that developers love to use. ## Core Principle A good API is intuitive, consistent, and hard to misuse. Design for the consumer, not the implementation. ## REST Fundamentals ### Resource Naming | Good | Bad | Why | |------|-----|-----| | `/users` | `/getUsers` | Nouns, not verbs | | `/users/123` | `/user?id=123` | Path params for identity | | `/users/123/orders` | `/getUserOrders` | Hierarchical resources | | `/search?q=term` | `/search/term` | Query params for filters | ### HTTP Methods | Method | Purpose | Idempotent | Safe | |--------|---------|------------|------| | GET | Read resource | Yes | Yes | | POST | Create resource | No | No | | PUT | Replace resource | Yes | No | | PATCH | Partial update | No* | No | | DELETE | Remove resource | Yes | No | ### Status Codes | Code | Meaning | When to Use | |------|---------|-------------| | 200 | OK | Successful GET, PUT, PATCH | | 201 | Created | Successful POST | | 204 | No Content | Successful DELETE | | 400 | Bad Request | Validation error | | 401 | Unauthorized | Missing authentication | | 403 | Forbidden | Authenticated but not allowed | | 404 | Not Found | Resource doesn't exist | | 409 | Conflict | State conflict (duplicate) | | 429 | Too Many Requests | Rate limited | | 500 | Internal Error | Server bug | ## Contract-First Design 1. **Define the contract** (OpenAPI/Swagger) 2. **Review with consumers** before coding 3. **Generate server stubs** from contract 4. **Implement bu