API Fundamentals
What an API contract is, and how a request becomes a response.
Concept guideUpdated 21 days ago (29 Sept 2026) by Developer B
API Fundamentals
What an API is
A contract. The client promises to send requests in an agreed shape; the server promises a response in an agreed shape. Everything else — language, framework, database — is the server's private business.
The shape of a request
POST /api/assessments HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
{ "memberId": "abc", "skillId": "def", "level": 3 }
- Method says what kind of operation: GET reads, POST creates, PATCH modifies, DELETE removes.
- Headers carry metadata: who you are, what format you send.
- Body carries the payload.
Status codes that matter
| Code | Meaning | Use it when |
|---|---|---|
| 200 | OK | The read or update worked |
| 201 | Created | A POST made something new |
| 400 | Bad Request | The input failed validation |
| 401 | Unauthorized | We do not know who you are |
| 403 | Forbidden | We know, and you may not |
| 404 | Not Found | No such resource, or you may not see it |
| 409 | Conflict | It clashes with current state |
| 500 | Server Error | We broke, not you |
The 401/403 distinction matters: 401 means authenticate, 403 means you are authenticated and still not allowed.
Idempotency
GET, PUT and DELETE should be safe to repeat. POST usually is not. If a client retries after a timeout, will you create a duplicate? If yes, you need an idempotency key.
Where things go wrong
- Validation that only runs in the browser.
- Authorization checked in the UI but not on the server.
- Error responses with a different shape per endpoint.
- Pagination without a stable sort, so rows repeat across pages.