Course notes: designing REST APIs your AI features can live with
Notes from Hour 07: resource naming, streaming responses and versioning when model outputs change shape.
These are the key ideas from Hour 07 of Learning Development with AI. The full lesson builds the API step by step; this page is the summary to keep open while you work.
Name resources, not prompts
Expose what the feature is, not how it works today: POST /summaries, not POST /run-gpt-prompt. The model behind a summary will change; the resource should not.
Stream long answers
Model responses can take seconds. Stream them with server-sent events so the interface shows text as it arrives, and send a final event with usage and an id the client can use to report problems.
POST /summaries HTTP/1.1
Accept: text/event-stream
Content-Type: application/json
{"documentId": "doc_123", "length": "short"}Version the output, not just the URL
When a new model changes the shape of what you return (new fields, different structure), add a schemaVersion field to the response and validate every response against that schema before sending it. Clients then fail loudly instead of rendering nonsense.
The lesson adds request validation, idempotency keys and error formats on top of these three ideas.