api-design

Purpose

Create consistent, well-designed APIs.

REST Conventions

Reference: standards/rest-conventions.md

HTTP Methods

| Method | Use Case | Idempotent | |--------|----------|------------| | GET | Retrieve resource | Yes | | POST | Create resource | No | | PUT | Replace resource | Yes | | PATCH | Partial update | No | | DELETE | Remove resource | Yes |

URL Patterns

GET    /users           # List users
GET    /users/:id       # Get user
POST   /users           # Create user
PUT    /users/:id       # Replace user
PATCH  /users/:id       # Update user
DELETE /users/:id       # Delete user

GET    /users/:id/posts # Nested resource

Response Status Codes

| Code | Meaning | Use When | |------|---------|----------| | 200 | OK | Successful GET, PUT, PATCH | | 201 | Created | Successful POST | | 204 | No Content | Successful DELETE | | 400 | Bad Request | Validation error | | 401 | Unauthorized | Auth required | | 403 | Forbidden | Auth insufficient | | 404 | Not Found | Resource doesn't exist | | 422 | Unprocessable | Business rule violation | | 500 | Server Error | Unexpected error |

Error Response Format

Reference: standards/error-responses.md

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Versioning

Reference: standards/versioning.md

Options:

• URL: /api/v1/users
• Header: Accept: application/vnd.api.v1+json

Recommendation: URL versioning for simplicity

Endpoint Documentation

Use template: templates/endpoint-doc.md