API design
Words made simple
A few useful meanings before you read the explanation.
- API
- A way for one piece of software to ask another for data or an action. A claims API might return the current status of a claim.
- AI
- Software techniques for tasks such as recognizing patterns, understanding language or generating content.
- Durable
- Able to retain progress and recover across interruptions. Durable workflows require appropriate storage and retry behavior.
More words from this lesson
- Idempotency
- Making a repeated request have the same intended business effect as one request. It helps avoid duplicate submissions or payments.
- Authentication
- Checking who a user or service is, such as by verifying a login session.
- Authorization
- Checking what that identity is allowed to read or do. Being logged in does not grant access to every record.
| API | Contract |
|---|---|
POST /ai/conversations | Create an authorized session; server assigns ownership |
POST /ai/conversations/:id/messages | Validate bounded message, record it, return safe stream or run reference |
GET /ai/runs/:id | Return public phase, outcome, safe errors, and review requirement after ownership check |
POST /documents | Validate upload intent and permissions; issue restricted upload path; return document/job IDs |
GET /documents/:id/status | Return parse/index/review status without exposing unauthorized sources |
POST /claim-drafts | Create validated proposal with source references and version |
PATCH /claim-drafts/:id | Require expected version; edits produce new hash and invalidate prior approval |
POST /claim-drafts/:id/approvals | Bind authenticated decision to exact version/hash/action; never accept model-generated approval |
POST /claim-drafts/:id/submit | Require valid approval and scoped idempotency key; return durable receipt or explicit pending outcome |
POST /ai/runs/:id/resume | Authenticate ownership/reviewer; validate pending input event; reject stale/duplicate invalid resumes |
POST /support-tickets | Create a permitted, deduplicated escalation with bounded case context |
- Apply CSRF protection where cookie-authenticated mutation routes require it, enforce origin/authentication policy, and use appropriate error semantics.
- A pending task may return
202; a chat sentence claiming success cannot substitute for a claim receipt.
Can you explain it without the notes?
API design
Use your own words. Explain an example and one limitation before checking the explanation.
Check your explanation
Apply CSRF protection where cookie-authenticated mutation routes require it, enforce origin/authentication policy, and use appropriate error semantics. A pending task may return 202; a chat sentence claiming success cannot substitute for a claim receipt.
Turn this concept into a clear answer.
Practice this conceptAdapted from 13_AI.MD · “API design”. Examples are study fragments; framework behavior can depend on your version.