api-design-first

API Design First

Design RESTful APIs using design-first principles with comprehensive OpenAPI 3.0 specifications.

When to Use

• User asks to design an API or create an API spec
• Planning endpoints, modeling request/response schemas
• Discussing API versioning or OpenAPI/Swagger documentation
• Even if they just say "design the API" or "create the OpenAPI spec"

Design Principles

1. API-First Mindset

• Design the API contract before implementation
• Use OpenAPI 3.0 as the source of truth
• Generate code from specifications, not vice versa

2. RESTful Design

• Use nouns for resources (not verbs)
• Leverage HTTP methods semantically
• Implement proper status codes
• Support filtering, pagination, and sorting

3. Consistency

• Follow naming conventions throughout
• Use consistent request/response formats
• Maintain backward compatibility with versioning

Resource Naming

GET    /users              # List users
GET    /users/{id}         # Get specific user
POST   /users              # Create user
PUT    /users/{id}         # Update user (full)
PATCH  /users/{id}         # Partial update
DELETE /users/{id}         # Delete user
GET    /users/{id}/orders  # Sub-resource collection

HTTP Status Codes

Code	Usage
200	Successful GET, PUT, PATCH
201	Successful POST (resource created)
204	Successful DELETE
400	Bad request (validation error)
401	Unauthorized
403	Forbidden
404	Resource not found
409	Conflict (duplicate, etc.)
422	Unprocessable entity
429	Rate limited
500	Server error

Request/Response Patterns

Pagination

{
  "data": [...],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  },
  "links": {
    "self": "/users?page=1",
    "next": "/users?page=2",
    "last": "/users?page=8"
  }
}

Error Response

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