Designing APIs¶

Workflows¶

[ ] Resources: Identify resources and relationships
[ ] Endpoints: Define URL structure and methods
[ ] Request/Response: Define payloads and schemas
[ ] Errors: Define error responses
[ ] Document: Create OpenAPI spec

REST Principles¶

Resource Naming¶

Use nouns, not verbs: /users not /getUsers
Use plural: /users not /user
Use kebab-case: /user-profiles not /userProfiles
Nest for relationships: /users/{id}/orders

HTTP Methods¶

Method	Purpose	Idempotent
GET	Read	Yes
POST	Create	No
PUT	Replace	Yes
PATCH	Update	Yes
DELETE	Remove	Yes

Status Codes¶

Code	Meaning
200	Success
201	Created
204	No Content
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Conflict
422	Unprocessable Entity
500	Internal Server Error

Error Response Format¶

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

Versioning¶

URL Versioning (Recommended)¶

GET /api/v1/users
GET /api/v2/users

Header Versioning¶

GET /api/users
Accept: application/vnd.api+json;version=1

Pagination¶

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}

OpenAPI Example¶

openapi: 3.0.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'