API Design for AI Services
Common Mistakes
1. Exposing model names in the API. model: "gpt-4o" in the request schema forces every consumer to know and specify the model. When the platform upgrades the model, all consumers must update. Expose capability tiers, not model names.
2. Not returning citations with clinical responses. A clinical AI response that does not cite its sources cannot be verified by a clinician and is not suitable for clinical use. The API must always include source citations in responses to clinical queries.
3. No streaming support for interactive use cases. An AI API that buffers the full response before returning adds 5–30 seconds of perceived latency to an interactive clinical workflow. Streaming (SSE) is not optional for interactive clinical AI features.
Key Takeaways
- Expose AI capability tiers (not model names) to decouple consumers from model upgrades
- All AI API responses must include request_id for end-to-end traceability
- Clinical AI responses must always include source citations
- Streaming (SSE) is required for interactive AI features where users are watching the response generate
- Maintain at least 6-month deprecation windows for healthcare API versions