api-designlisted

# API Design Patterns Guidelines for designing REST APIs. ## Resource-Oriented Design Design around resources, not actions. ### Good - `GET /users/123` — Get a user - `POST /users` — Create a user - `PUT /users/123` — Update a user - `DELETE /users/123` — Delete a user ### Avoid - `GET /getUser` — Action-oriented - `POST /createNewUser` — Redundant with HTTP method ## HTTP Methods | Method | Purpose | Idempotent | |--------|---------|-----------| | GET | Retrieve | Yes | | POST | Create | No | | PUT | Full update | Yes | | PATCH | Partial update | No | | DELETE | Delete | Yes | ## Status Codes ### 2xx Success - `200 OK` — Request succeeded - `201 Created` — Resource created (include Location header) - `204 No Content` — Success, no response body ### 4xx Client Error - `400 Bad Request` — Invalid input - `401 Unauthorized` — Authentication required - `403 Forbidden` — Authenticated, not allowed - `404 Not Found` — Resource doesn't exist - `422 Unprocessable Entity` — Valid format, semantic error ### 5xx Server Error - `500 Internal Server Error` — Unexpected error - `503 Service Unavailable` — Temporarily down ## Error Responses Consistent error format: ```json { "error": { "code": "INVALID_INPUT", "message": "User email is required", "details": { "field": "email" } } } ``` ## Request/Response Bodies ### JSON Structure - Use camelCase for fields - Flat structure (max 2-3 nesting levels) - Avoid redundant wrappers ```json { "userId":