Framework

API specs are PRDs for backend. Specify:

  • Endpoints: List all (GET /users, POST /recommendations, etc.)
  • Request format: What parameters, data types, defaults
  • Response format: Success (200), failures (400, 404, 500), example JSON
  • Authentication: How do you authenticate requests?
  • Rate limits: Calls per second/hour per user
  • Versioning: How do you handle API changes?

Example:

GET /recommendations?user_id=123&limit=10

Response (200):
{
  "recommendations": [
    {"id": "456", "title": "...", "confidence": 0.87}
  ],
  "timestamp": "2026-04-15T10:00:00Z"
}

Errors (400, 404, 429): Documented
Rate limit: 100 calls/minute per user

Key Takeaways

  • API specs prevent integration surprises. Clear spec = faster integration.
  • Version your API from day one. Easier than retrofitting versioning later.