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

Download .md Done editing

Title

Type

What it is, why we use it, the architecture and real examples. The material behind a Concept Sharing session.

Summary

Body

# 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

```http
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

1. Validation that only runs in the browser.
2. Authorization checked in the UI but not on the server.
3. Error responses with a different shape per endpoint.
4. Pagination without a stable sort, so rows repeat across pages.

Markdown with tables, code blocks and task lists.