api-design

API Design Skill

Design APIs that are consistent, discoverable, and hard to misuse. Conventions over configuration.

1. When to Apply This Skill

Trigger conditions:

• Designing new API endpoints or a full API surface
• "What should this endpoint look like?"
• Planning API versioning or migration
• Reviewing API contracts for consistency
• Building an API spec or OpenAPI document

2. REST Resource Naming

URL Convention

# Resources are nouns, plural, lowercase, kebab-case
GET    /api/v1/customers                  # List
GET    /api/v1/customers/{id}             # Get one
POST   /api/v1/customers                  # Create
PUT    /api/v1/customers/{id}             # Full update
PATCH  /api/v1/customers/{id}             # Partial update
DELETE /api/v1/customers/{id}             # Delete

# Nested resources for strong ownership
GET    /api/v1/customers/{id}/orders      # Customer's orders
POST   /api/v1/customers/{id}/orders      # Create order for customer

# Actions (when CRUD doesn't fit) — verb suffix
POST   /api/v1/orders/{id}/cancel         # Action on resource
POST   /api/v1/reports/generate           # Trigger async operation

Naming Rules

Rule	Good	Bad
Plural nouns	/customers	/customer, /getCustomers
Kebab-case	/order-items	/orderItems, /order_items
No verbs in path	/customers (POST = create)	/createCustomer
Consistent nesting depth	Max 2 levels: /customers/{id}/orders	/customers/{id}/orders/{id}/items/{id}/details
No trailing slash	/customers	/customers/

3. Request & Response Envelope

Success Response

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

List Response (with pagination)

{
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 142,
    "total_pages": 6
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Invalid email format" },
      { "field": "age", "message": "Must be at least 18" }
    ]
  }
}