1 REST APIs
REST (Representational State Transfer) is an architectural style widely used for web APIs. A REST API usually exposes resources through URLs — /users, /users/1001, /devices, /orders/72381 — and operations happen through HTTP methods: GET /users/1001 retrieves a user, POST /users creates one, PATCH /users/1001 modifies it, DELETE /users/1001 removes it. HTTP itself is a stateless request/response protocol whose semantics are shared across HTTP/1.1, HTTP/2 and HTTP/3, currently defined in RFC 9110.
This distinction matters: REST is not the same thing as HTTP. REST is an architectural style; HTTP is a protocol. Most REST APIs run over HTTP or HTTPS, but HTTP also carries plenty of traffic that isn't REST at all. And an API returning JSON isn't automatically "a REST API" either — you'll constantly meet APIs described loosely as "REST" that don't perfectly follow REST principles. In the real world, understanding how the API actually behaves matters far more than arguing about the label.
2 Anatomy of a Request & Response
An HTTP API request generally contains a method, a URL, headers, and (often) a body:
POST https://api.example.com/v1/users
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
Accept: application/json
{
"username": "jsmith",
"department": "Finance",
"enabled": true
}Method (POST) says we want to create or submit something. URL is where the request goes. Authorization carries the credentials used to authorise the request. Content-Type tells the server the body is JSON. Accept tells the server we'd like the response as JSON too. Body is the actual data being sent.
The server might respond:
HTTP/1.1 201 Created
Content-Type: application/json
Location: /v1/users/82371
{
"id": 82371,
"username": "jsmith",
"department": "Finance",
"enabled": true
}Important components: the status code tells you whether the operation succeeded (Lesson 2 covers this in full); response headers and the response body usually carry the requested information or additional error detail.
3 The Five Core HTTP Methods
GET /api/users might return every user; GET /api/users/1005 retrieves just that one. GET requests should never make destructive changes.POST /api/users → 201 Created) or triggers an action — e.g. POST /api/devices/8391/disable or POST /api/users/1042/reset-password. Not every enterprise API follows perfect REST conventions here.PUT /api/users/1005 may require the complete representation of the resource, not just the changed fields.PATCH /api/users/1005 with just {"department": "Cybersecurity"} changes one field. PATCH is common in modern REST APIs.DELETE /api/users/1005 might return 204 No Content — an empty response body doesn't mean the request failed.4 Idempotency
An operation is idempotent when repeating it has the same effect as doing it once. DELETE /users/123 repeated shouldn't keep deleting additional resources — PUT and DELETE are normally considered idempotent; POST usually isn't.
🔮 Think it through
An application sends POST /payments. The server processes the payment successfully, but the client times out before receiving the response, and the application retries automatically. What could go wrong, and how do financial APIs typically prevent it?
Reveal the answer
Without safeguards, the customer could be charged twice — POST isn't idempotent, so a retried "create payment" request looks like a second, separate payment to the server. Financial APIs commonly guard against this with an Idempotency-Key header or another transaction identifier: the server recognises a repeated key and returns the original result instead of processing the payment again.
5 JSON & Its Data Types
JSON (JavaScript Object Notation) is the most common format for exchanging data through APIs, designed to be both machine-readable and reasonably easy for humans to follow:
{
"username": "jsmith",
"enabled": true,
"loginCount": 17
}"name": "John Smith""age": 35"enabled": true — only true/false, never quoted."manager": null — no value present."department": { "id": 10, "name": "Security" } — a nested set of key/value pairs."roles": ["administrator", "security-reader", "auditor"] — an ordered list.Real APIs often return deeply nested data:
{
"user": {
"id": "10045",
"username": "jsmith",
"authentication": {
"mfaEnabled": true,
"methods": [
{ "type": "FIDO2", "registered": true },
{ "type": "TOTP", "registered": true }
]
}
}
}Learn to mentally follow the hierarchy — here, user → authentication → methods → type. Being able to trace a path like that instantly is exactly what makes a JSON response feel readable instead of like noise.
6 JSON Syntax Errors & JSON vs XML
A common troubleshooting problem is invalid JSON. A trailing comma {"username": "jsmith", "enabled": true,} can break parsing. Unquoted property names ({username: "jsmith"}) are invalid — JSON requires quotation marks around keys. And {"enabled": True} is wrong too; correct JSON uses lowercase true, not True.
Older enterprise applications frequently use XML instead. The JSON {"username": "jsmith", "enabled": true} might appear as:
<user>
<username>jsmith</username>
<enabled>true</enabled>
</user>You'll meet both formats in banking, government, manufacturing, healthcare, telecommunications, aviation and large multinational companies — never assume JSON's dominance in new systems means XML has disappeared. It hasn't (Lesson 5 covers SOAP/XML in depth).
Lesson Outcome
You should now be able to explain why REST and HTTP aren't the same thing, read a raw HTTP request and response and name every part of it, use the five core HTTP methods correctly, explain idempotency and why it matters for payments, and read (and spot syntax errors in) JSON, including nested structures. Lesson 2 covers everything that travels alongside the method and body — headers, parameters, and the full range of status codes.