skill-api-designlisted

# Skill: API Design Design APIs as contracts. Versions matter. Backward compatibility is non-negotiable. ## REST Principles - **Noun-based URLs**: `/users` not `/getUsers` - **HTTP methods**: GET (read), POST (create), PUT (update), DELETE (remove) - **Status codes**: 200 (OK), 201 (created), 400 (bad request), 401 (auth), 404 (not found), 500 (error) - **Consistency**: Same patterns across all endpoints ## Versioning Strategy **URL path** (explicit, clear): ``` GET /api/v1/users # v1 API GET /api/v2/users # v2 API (breaking change) ``` **Header** (less visible, prefer path): ``` GET /api/users Header: API-Version: 2 ``` ## Breaking Changes = Major Version ``` v1.0 → v2.0: User response format changed v1.1 → v1.2: New optional field added (backward-compatible) v1.0 → v1.1: Bug fix (patch) ``` ## API Contract (OpenAPI/Swagger) ```yaml paths: /users/{id}: get: summary: Get user parameters: - name: id in: path required: true schema: { type: string } responses: '200': description: User found content: application/json: schema: $ref: '#/components/schemas/User' '404': description: Not found ``` ## Error Responses ```json { "error": "not_found", "message": "User not found", "code": 404, "details": { "resource": "user", "id": "user-123" } } ``` ## Rate Limiting ``` Header: X-RateLimit-Limit: 1000 Head