api

APIs are contracts. Breaking changes break consumers. Resources are nouns, not verbs. HTTP methods define actions. Status codes are not decorative. 200 for errors is a lie. AgentDB read-start has run. Check existing API patterns in codebase. Identify API versioning strategy in use (URL path, header, none). Skill-specific: skills/api/reference/api-research.md

1. RESOURCE NAMING

   • URLs are nouns, plural, kebab-case: /api/v1/users, /api/v1/team-members
   • HTTP methods are the verbs: GET/POST/PUT/PATCH/DELETE
   • Sub-resources for relationships: /api/v1/users/:id/orders
   • Actions (sparingly): POST /api/v1/orders/:id/cancel
   • (gate: no verb in URL path, no singular resource names, no snake_case in URL)

2. STATUS CODES — use semantically, never 200 for errors

   200 OK · 201 Created (+ Location header) · 204 No Content
   400 Bad Request · 401 Unauthorized · 403 Forbidden · 404 Not Found
   409 Conflict · 422 Unprocessable Entity · 429 Too Many Requests
   500 Internal Server Error · 502 Bad Gateway · 503 Service Unavailable (+ Retry-After)
   

   (gate: POST returns 201, DELETE returns 204, errors never return 200)

3. VALIDATE ALL INPUT before any processing

   • Schema validation with Zod (TS) or Pydantic (Python) on every endpoint
   • Return 422 with structured field errors on validation failure
   • (gate: no endpoint processes input without schema.safeParse / model.validate)

4. RESPONSE SHAPE — consistent envelope

   • Single resource: { "data": { ... } }
   • Collection: { "data": [...], "meta": { total, page, per_page }, "links": { self, next, last } }
   • Error: { "error": { "code": "snake_case_code", "message": "...", "details": [...] } }
   • (gate: all responses use envelope; no bare objects; error.code is machine-readable)

5. PAGINATION — mandatory for all list endpoints

   • Cursor (?cursor=...&limit=20): use for feeds, infinite scroll, >10K rows
   • Offset (?page=N&per_page=20): use for admin dashboards, search with page jumps
   • Return next_cursor as opaque string — agents must not compute it from math
   • (gate: no list endpoint returns unbounded results)

6. VERSIONING

   • URL path versioning: /api/v1/, /api/v2/ (recommended)
   • Max 2 active versions; add Sunset header before removal
   • Non-breaking (no new version): add fields, add optional params, add endpoints
   • Breaking (new version required): remove/rename fields, change types, change URL structure
   • (gate: breaking change without version bump = blocked)

7. RATE LIMITING — expose via headers on every response

   X-RateLimit-Limit: 100
   X-RateLimit-Remaining: 95
   X-RateLimit-Reset: <unix-timestamp>
   Retry-After: 60   # on 429 only
   

   (gate: 429 response always includes Retry-After)

8. IDEMPOTENCY — mandatory for state-changing ops in distributed/agentic contexts

   • Accept Idempotency-Key header on POST/PATCH
   • Cache result keyed by idem:<key> with 24h TTL; return cached on repeat
   • Required for: payments, orders, bulk imports, any agent-called endpoint
   • (gate: agent-facing POST endpoints either are idempotent by design OR support Idempotency-Key)

9. HEALTH ENDPOINTS

   GET /health          # Liveness: 200 if process alive
   GET /health/ready    # Readiness: 200 if all dependencies up
   GET /health/startup  # Startup: 200 once init complete
   

   • Response: { "status": "ok|degraded", "version": "...", "dependencies": { "db": "ok" } }
   • 503 if critical dependency down; 200 + "degraded" if non-critical
   • (gate: every new service exposes /health and /health/ready)

10. AGENTIC CLIENT DESIGN — when API is called by AI agents

    • Every state-changing endpoint: idempotent OR requires Idempotency-Key (document which)
    • Distinct error codes per failure mode — agents parse codes to decide retry vs abort vs escalate
    • Batch endpoints for high-frequency reads: GET /api/v1/users/batch?ids=a,b,c
    • Return next_cursor as direct string, never derivable by offset math
    • (gate: agent-facing APIs documented with retry-safety posture per endpoint)

<anti_patterns> /getUsers, /createOrder. Use HTTP methods for actions. { "status": 200, "success": false }. Use HTTP status codes. Trusting user input. Validate everything with schemas. Stack traces in error responses. Generic messages for users. Returning all records. Pagination is mandatory for lists. </anti_patterns>

<on_complete> agentdb write-end '{"skill":"api","endpoints_created":,"validation":"zod|pydantic|none","pagination":"cursor|offset|none","versioning":"v1|none"}'

Record endpoints added and patterns used. </on_complete>