API Design

REST API design standards shared across TypeScript and Golang web APIs. Apply these conventions in all new endpoints and when reviewing existing ones.

Recommended model: Haiku (reference lookups and convention checks)

URL Conventions

• Resource names: plural nouns, lowercase, kebab-case — /users, /marketing-plans
• No verbs in URLs — actions are expressed via HTTP method, not path
• Nested resources: /users/{id}/posts — nest only one level deep
• Path parameters: {id} not :id in docs; use framework convention in code
• Versioning: /v1/ prefix on all routes — /v1/users/{id}

HTTP Methods

Response Envelope

All responses use this shape:

{
  "data": { ... } | null,
  "error": { "code": "string", "message": "string", "details": {} } | null,
  "meta": { "nextCursor": "string", "total": 100 }
}

• data is null when there is an error
• error is null on success
• meta is included only for paginated responses

Error Shape

{
  "code": "VALIDATION_ERROR",
  "message": "Human-readable description",
  "details": { "field": "reason" }
}

Standard error codes: VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, RATE_LIMITED, INTERNAL_ERROR

HTTP Status Codes

Pagination

Use cursor-based pagination for all list endpoints:

• Request: GET /v1/posts?after=<cursor>&limit=20
• Default limit: 20; max limit: 100
• Response meta: { "nextCursor": "<opaque>", "total": 500 }
• nextCursor is null when no more pages

Never use offset-based pagination (?page=2) — it breaks under concurrent inserts/deletes.

Authentication

• Token in Authorization: Bearer <jwt> header only
• Never accept tokens in query params or cookies for APIs
• Validate in middleware before hitting route handlers

Rate Limiting

• Respond with 429 when limit exceeded
• Include headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After (seconds)

Naming

• Request/response field names: camelCase in JSON (TypeScript) or snake_case (Go with json:"field_name" tags)
• Timestamps: ISO 8601 UTC — "2024-01-15T10:30:00Z"
• IDs: strings (not integers) — use CUID, UUID, or nanoid