Api Design

API Design Patterns

REST Resource Design

URL Structure

GET    /api/v1/resources          — List (with pagination)
GET    /api/v1/resources/:id      — Get single
POST   /api/v1/resources          — Create
PUT    /api/v1/resources/:id      — Full update
PATCH  /api/v1/resources/:id      — Partial update
DELETE /api/v1/resources/:id      — Delete

# Nested resources
GET    /api/v1/users/:id/posts    — User's posts
POST   /api/v1/users/:id/posts    — Create post for user

# Actions (non-CRUD)
POST   /api/v1/orders/:id/cancel  — Action on resource
POST   /api/v1/auth/login         — Authentication
POST   /api/v1/auth/refresh       — Token refresh

Naming Rules

• Plural nouns for resources (/users, not /user)
• Kebab-case for multi-word (/user-profiles, not /userProfiles)
• No verbs in URLs (/users, not /getUsers)
• No trailing slashes

HTTP Status Codes

| Code | When to Use | |------|-------------| | 200 | Successful GET, PUT, PATCH, or DELETE | | 201 | Successful POST (resource created). Include Location header. | | 204 | Successful DELETE with no response body | | 400 | Invalid request (validation error, malformed JSON) | | 401 | Not authenticated (missing or invalid credentials) | | 403 | Authenticated but not authorized | | 404 | Resource not found | | 409 | Conflict (duplicate resource, version mismatch) | | 422 | Semantically invalid (valid JSON, but business logic rejects it) | | 429 | Rate limit exceeded. Include Retry-After header. | | 500 | Server error (never expose internals) |

Response Formats

Success (Direct)

{
  "id": "uuid",
  "name": "Example",
  "createdAt": "2025-01-01T00:00:00Z"
}

Success (Envelope)

{
  "data": { ... },
  "meta": {
    "page": 1,
    "perPage": 20,
    "total": 150
  }
}

Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  }
}

Pagination

Cursor-Based (Recommended)

GET /api/users?cursor=abc123&limit=20

Response:
{
  "data": [...],
  "pagination": {
    "nextCursor": "def456",
    "hasMore": true
  }
}

Offset-Based

GET /api/users?page=2&perPage=20

Response:
{
  "data": [...],
  "pagination": {
    "page": 2,
    "perPage": 20,
    "total": 150,
    "totalPages": 8
  }
}

Authentication Patterns

JWT Bearer Token

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Access token: short-lived (15-60 min)
Refresh token: long-lived (7-30 days), stored securely

API Key

X-API-Key: sk_live_abc123...

Use for: server-to-server, public data APIs
Never for: user-facing authentication

OAuth 2.0 Flows

• Authorization Code — Web apps (most secure)
• PKCE — SPAs and mobile apps
• Client Credentials — Service-to-service
• Device Code — CLI tools and IoT

Rate Limiting

Include headers in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1672531200
Retry-After: 60

Common limits:

• Anonymous: 60 requests/minute
• Authenticated: 1000 requests/minute
• Auth endpoints (login): 10 requests/minute (brute-force prevention)

Versioning

URL Path (Recommended)

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

Header

Accept: application/vnd.myapi.v2+json

Query Parameter

/api/users?version=2

Caching

# Immutable resources
Cache-Control: public, max-age=31536000, immutable

# Dynamic but cacheable
Cache-Control: public, max-age=60, stale-while-revalidate=30

# Never cache
Cache-Control: no-store

# ETag for conditional requests
ETag: "abc123"
If-None-Match: "abc123"  → 304 Not Modified

Security Headers

Content-Type: application/json
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Strict-Transport-Security: max-age=31536000

Input Validation Rules

• Validate ALL input (body, query, params, headers)
• Whitelist allowed fields (don't pass raw input to DB)
• Set max lengths on strings
• Set min/max on numbers
• Validate email, URL, UUID formats
• Sanitize HTML in text fields
• Reject unknown fields (strict mode)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: iwritec0de
• Source: iwritec0de/app-dev
• License: MIT

Install and usage instructions live in the source repository linked above.