Computing Foundations › APIs and the Web › Day 23
Day 23: REST Fundamentals: Resources and Verbs
After this lesson you will be able to read almost any web API as a set of resources at addresses acted on by standard verbs, map CRUD onto HTTP methods, and reason about statelessness, idempotency, and good URL design — the architecture behind nearly every API you will ever call.
Hands-on lab for this lesson
Lab files on GitHub: https://github.com/ai-roadmap-365/ai-roadmap-365.github.io/tree/main/labs/sections/computing-foundations/day-023-rest-fundamentals-resources-and-verbs
- Get the hands-on files. Clone the labs repository once (you can reuse this clone for every lesson). This works on macOS, Linux, and Windows (PowerShell or WSL):
git clone https://github.com/ai-roadmap-365/ai-roadmap-365.github.io.git cd ai-roadmap-365.github.io - Open this lesson's lab. Move into the directory for this specific day. Every lab lives at the same predictable path — section / subsection / week / day:
cd labs/sections/computing-foundations/day-023-rest-fundamentals-resources-and-verbs - Read the lab guide. Open `README.md` in that directory. It lists the exact commands, what each does, the expected output, and how to check your work — read it before running anything.
- Run it and check your work. Follow the README's "How to run" section: run the example first to see the finished result, then complete the numbered exercises in `starter/`, then run the tests. The tests pass (exit 0) only when your work is correct.
bash tests/run_tests.sh # or the test command named in the lab README
You can also open the lab as a local page (works offline, shows the file tree and expected output).
Learning objectives
By the end of this lesson you will be able to:
- Define REST as an architectural style and explain the resource-and-verb model, including why URLs name nouns (/users/1) rather than actions (/getUser)
- Map the four CRUD operations onto the HTTP verbs GET, POST, PUT, PATCH, and DELETE, and state which verb targets a collection versus an item
- Explain statelessness and why it lets a REST service scale horizontally behind a load balancer
- Distinguish a resource from its representation, and identify JSON as the common representation format
- Apply safety and idempotency to decide which verbs are safe to retry, and why blindly retrying a POST is risky
- Compare REST with RPC/gRPC and GraphQL at a high level and choose the right style for a given situation
- Run a full create-read-update-delete cycle against a real REST API with curl and read the status codes and representations it returns
Prerequisites
- Day 18 (HTTP requests, responses, and methods) and Day 22 (what an API is)
- A terminal with curl and network access; python3 optional for pretty-printing JSON
Why this matters
-
Most APIs you meet are REST-shaped, so learning one teaches you most of the next.
-
The predictability is the product. Once you know the pattern, you can guess an endpoint correctly before reading the documentation.
-
POSTis not idempotent, and today that fact acquires teeth: it is the difference between a robust integration and a double charge. -
Statelessness is why services scale, and it is why your credential travels on every request rather than once at login.
-
Designing your own API well starts with getting resources and verbs right.
The idea in plain language
-
REST names things, and HTTP supplies the actions. Paths are nouns; methods are verbs.
-
A collection holds items.
/usersis all of them;/users/1is one. -
Four operations cover almost everything: create, read, update, delete.
-
Every request stands alone. The server remembers nothing between them, which is what lets a thousand servers answer interchangeably.
-
You never touch a resource, only representations of it — usually JSON snapshots of its current state.
Historical background
-
Roy Fielding described REST in his 2000 dissertation, as an architectural style rather than a standard or a specification.
-
He was describing the web itself, and arguing that HTTP’s existing design was already the answer people kept trying to replace.
-
The alternative at the time was SOAP — XML envelopes, generated stubs, a toolchain on both ends, and one endpoint that all operations tunnelled through.
-
REST won on simplicity. No code generation, no toolchain, and a URL you could paste into a browser.
-
The name drifted almost immediately. “REST API” today usually means “JSON over HTTP with sensible paths”, which Fielding would not recognise as REST.
-
That drift is fine to know about and pointless to argue over. Learn the pattern people actually use.
What it is — and what it is not
It is:
- A set of constraints on how to use HTTP, not a protocol of its own.
- Resource-oriented: the path names a thing, the method names the action.
- Stateless, cacheable and uniform — the properties that make it scale.
It is not:
-
Not a standard. There is no REST specification to comply with, which is why APIs vary so much while all claiming the name.
-
Not “JSON over HTTP”. That is the common usage, and it is a subset.
-
Not always the right shape. Operations that are genuinely not CRUD — “translate this”, “run this simulation” — fit awkwardly, and forcing them is worse than not.
-
Not a guarantee of good design. A REST-shaped API can still be badly named, inconsistent and undocumented.
Why it was created and what problems it solves
-
Predictability. If you know
/usersand/users/1, you can guess/users/1/orders— and be right. -
No toolchain. A URL and a method are all a client needs, in any language.
-
Cacheability. Because
GETis safe, anything on the path may keep a copy, and the web’s whole caching infrastructure applies for free. -
Scalability through statelessness. Any server can answer any request.
-
Visibility. An intermediary can understand a request without understanding the application, which is what makes proxies, gateways and logs useful.
How it works
Resources, collections, and items
-
A resource is anything worth naming: a user, an order, a photo, a comment.
-
A collection holds many —
/users. -
An item is one member, addressed by identifier —
/users/1. -
Collections nest naturally:
/users/1/ordersis that user’s orders, and/users/1/orders/42is one of them. -
Read a REST URL left to right and it reads like a path through a filing system.
-
The golden rule: paths are nouns. The moment a verb appears —
/getOrders,/users/1/delete— you have stopped doing REST and started inventing a bespoke vocabulary, which throws away the predictability that was the point.
The verbs, mapped to CRUD
| Operation | Verb | Target | What it does | Success |
|---|---|---|---|---|
| Read | GET | collection or item | Fetch a representation; change nothing | 200 |
| Create | POST | collection | Add an item; the server assigns the id | 201 |
| Update (replace) | PUT | item | Replace it entirely with your body | 200/204 |
| Update (partial) | PATCH | item | Change only the fields you sent | 200 |
| Delete | DELETE | item | Remove it | 200/204 |
-
You
POSTto a collection to create. The server assigns the id and usually returns201with the new resource and its address. -
You
GET,PUT,PATCHandDELETEan item you can already name. -
PUTreplaces;PATCHmerges. Leave a field out of aPUTand you may erase it. Leave it out of aPATCHand it is untouched. -
Reach for
PATCHto change one attribute, andPUTwhen you hold the complete new version.
Statelessness
-
Each request is self-contained: it carries everything the server needs to understand and authorise it.
-
The credential travels on every request, typically as
Authorization: Bearer <token>— there is no server-side session later requests ride on. -
That feels wasteful until you see what it buys. Any request can go to any copy of the server.
-
A provider can run a thousand identical servers, add and remove them as traffic changes, and restart any of them mid-conversation, and no client notices.
-
Statelessness is what turns “one server” into “as many as we need”.
Representations
{
"id": 1,
"name": "Ada Lovelace",
"email": "ada@example.org",
"role": "admin"
}
-
You never touch the resource, only a document describing its current state.
-
The same resource could be JSON, XML, HTML or binary. The resource (“user 1”) is separate from its representation (“this JSON”).
-
Acceptsays what you want;Content-Typesays what you got. -
The name is now readable. Representational State Transfer: you transfer representations of resource state back and forth.
Safety and idempotency
| Verb | Safe? | Idempotent? | Consequence |
|---|---|---|---|
GET | Yes | Yes | Cache and retry freely |
POST | No | No | Two identical calls may create two resources |
PUT | No | Yes | Replacing twice equals replacing once |
PATCH | No | Usually no | A relative change applied twice differs |
DELETE | No | Yes | Deleting a deleted item leaves it deleted |
-
The most important line is that
POSTis not idempotent. -
POST /orders, a timeout, and a retry can place two orders and charge twice. -
PUTandDELETEare safe to repeat, which is exactly why a flaky network is survivable for them and dangerous forPOST. -
Retry logic must know which verb it is retrying.
HATEOAS at a glance
{
"id": 1,
"name": "Ada Lovelace",
"_links": {
"self": { "href": "/users/1" },
"orders": { "href": "/users/1/orders" },
"edit": { "href": "/users/1", "method": "PUT" }
}
}
-
The strictest REST includes links telling the client what it can do next.
-
The client follows links rather than constructing URLs, exactly as you click through a web page instead of typing every address.
-
Most APIs called RESTful today skip this and let clients build URLs from documentation. That is the pragmatic reality.
-
Where an API does return links, follow them. Your client keeps working when the server reorganises its URLs.
An everyday analogy
A library catalogue.
| The library | REST |
|---|---|
| The shelf of all fiction | A collection, /books |
| One book with a number | An item, /books/1 |
| Its section, then its shelf, then the book | Nested paths |
| Read it | GET |
| Add a new one to the shelf | POST to the collection |
| Replace a damaged copy | PUT on the item |
| Correct one field on its card | PATCH |
| Withdraw it | DELETE |
- The shelf label is a noun. There is no shelf called “get books”.
- Reading a book twice changes nothing; that is safe. Withdrawing it twice
leaves it withdrawn; that is idempotent. Donating a book twice gives the library
two books, and that is
POST.
Examples in practice
-
GET /users?role=admin&_limit=10— filtering and limiting a collection with query parameters rather than a new endpoint. -
POST /usersreturning201with aLocationheader pointing at the new/users/7. -
PATCH /users/1with{"email": "new@example.org"}— one field changed, everything else untouched. -
PUT /users/1missing therolefield, which silently clears it. This is the most commonPUTmistake. -
DELETE /users/1twice, returning204then404— both correct, and the resource is gone either way.
Implications: security, privacy, performance, scalability, and cost
-
Security: predictable URLs mean guessable URLs.
/users/1implies/users/2exists, so authorisation must be checked per request, not assumed from the path. -
This is the most common REST vulnerability: an endpoint that checks you are logged in but not that the resource is yours.
-
Never put anything sensitive in a path. Paths appear in logs, in browser history and in
Refererheaders. -
Performance:
GETbeing safe is what makes caching possible, and a correctCache-Controlheader is often worth more than any server optimisation. -
Scalability: statelessness is the whole story. It is what allows horizontal scaling with no coordination.
-
Cost: a chatty client is an expensive one. Fetching a collection and then each item individually is the N+1 problem from yesterday, in REST clothing.
Alternatives: free, open source, and commercial
| Style | Type | Where it fits |
|---|---|---|
| REST | The default | Resource-shaped data, public APIs, anything cacheable |
| GraphQL | Free, open source | Clients that need to choose their own response shape |
| gRPC | Free, open source | Service-to-service, where speed beats readability |
| JSON-RPC | Free, open source | Genuinely operation-shaped work that is not CRUD |
| OpenAPI | Free, open source | Not an alternative — how you describe a REST API formally |
| Webhooks | The inverse | Events pushed to you, rather than polled — Day 26 |
-
GraphQL exists because REST over-fetches and under-fetches. One endpoint, and the client states exactly which fields it wants.
-
Its cost is caching and complexity. REST gets HTTP caching free; GraphQL has to build it.
-
Write an OpenAPI document for anything public. It generates the documentation, the client libraries and the tests.
Comparison with related concepts
| Term | What it actually is |
|---|---|
| Resource | A thing the API names |
| Collection | A resource holding many others |
| Item | One member of a collection |
| Representation | A serialised snapshot of a resource’s state |
| CRUD | Create, read, update, delete |
| Statelessness | The server remembers nothing between requests |
| HATEOAS | Responses carry links to what you can do next |
When to use it — and when not to
-
Use REST when your domain is made of things — users, orders, documents, datasets.
-
Use query parameters to filter, sort and page, rather than inventing an endpoint per variation.
-
Return
201with aLocationheader when you create something. It costs nothing and saves the client a request. -
Do not put verbs in paths. If you find yourself wanting to, the operation probably deserves to be a resource of its own — a “job”, a “run”, a “search”.
-
Do not use
GETfor anything that changes state. A crawler or a prefetcher will find it eventually. -
Do not force genuinely non-CRUD operations into REST. “Send this email”, “translate this text” — model these as resources you create, or accept that the style does not fit.
The AI connection
-
Model APIs are barely REST, and knowingly so:
POST /v1/messagescreates a completion, which is a resource in only the loosest sense. -
That is the right call. Generation is an operation, not a CRUD action on a stored thing, and pretending otherwise would help nobody.
-
The non-idempotent
POSTmatters more here than almost anywhere, because a retried generation is billed again and may return something different. -
Fine-tuning APIs are properly RESTful, because a training job genuinely is a resource: create it, poll it, list them, cancel one.
-
Vector databases expose REST too — collections of documents, items by id — and the pattern from today transfers directly.
Knowledge check
quiz:
question: "A client updates a user's email with `PUT /users/1` sending only `{\"email\": \"new@example.org\"}`. Afterwards the user's name and role are empty. What went wrong?"
options:
- "PUT replaces the entire resource, so fields omitted from the body were cleared"
- "The server rejected the partial body and reset the record to defaults"
- "PUT is not idempotent, so the repeated request overwrote the other fields"
- "The Content-Type header was missing, so the body was parsed incorrectly"
answer_index: 0
explanation: "PUT means \"make the resource be exactly this\". A body containing only the email describes a user with no name and no role, and the server complied. PATCH is the verb that merges rather than replaces."
Hands-on exercise
Exercise all five verbs against a real API and watch the status codes. Worked through fully in the Day 23 lab directory.
| What you are doing | Command |
|---|---|
| Read a collection | curl 'https://jsonplaceholder.typicode.com/posts?_limit=3' |
| Read one item | curl https://jsonplaceholder.typicode.com/posts/1 |
| Create | curl -i -X POST -H 'Content-Type: application/json' -d '{"title":"hi","userId":1}' .../posts |
| Replace | curl -i -X PUT -H 'Content-Type: application/json' -d '{"id":1,"title":"new","userId":1}' .../posts/1 |
| Merge | curl -i -X PATCH -H 'Content-Type: application/json' -d '{"title":"just this"}' .../posts/1 |
| Delete | curl -i -X DELETE .../posts/1 |
| Nested collection | curl '.../posts/1/comments?_limit=2' |
Expected output
HTTP/1.1 201 Created
{"title":"hi","userId":1,"id":101}
HTTP/1.1 200 OK
{"id":1,"title":"just this","body":"...","userId":1}
201for the create, with a server-assignedidyou did not choose.- The
PATCHkeptbodyanduserId. APUTwith the same partial body would not have.
Validate your work
- You used all five verbs and recorded the status code each returned
- You can explain why
POSTwent to the collection andPUTto the item - You demonstrated the difference between
PUTandPATCHon the same resource - You fetched a nested collection
- You can state which verbs are safe and which are idempotent, without looking
-
bash tests/run_tests.shreports 0 failures
Troubleshooting
-
POSTreturns the object with no id. MissingContent-Type, so the body was ignored. -
PUTreturns only the fields you sent. That isPUTworking correctly. UsePATCHif you meant to merge. -
A query string does nothing. The shell ate the
?and&. Quote the URL. -
DELETEreturns200and the resource is still there. Test APIs often fake writes. Read their documentation.
Common mistakes
- Verbs in paths.
/createUseris the tell. POSTto an item rather than to the collection.- Retrying a
POSTblindly after a timeout. - Using
PUTfor a partial update and clearing fields you never mentioned.
Practice assignment
-
Design the endpoints for a small domain — a library, a task tracker, a dataset registry — writing out every path and verb, with no verbs in any path.
-
Find a real API that violates the pattern and write down which rule it breaks and whether the break was justified.
-
Prove the
PUTfield-clearing behaviour on a test API, then fix the same change withPATCH. -
Write the retry rule you would put in a client: which verbs, which status codes, and what backoff.
Extension challenge
-
Build a five-endpoint REST API for one resource and exercise it with
curl. Implementing the server side makes the constraints obvious in a way reading cannot. -
Add an idempotency key to your create endpoint so a repeated
POSTreturns the original result rather than creating a second resource. This is the standard fix and worth implementing once. -
Write an OpenAPI document for your API and generate documentation from it.
-
Add
_linksto one response and write a client that navigates by following them rather than constructing URLs. Then change a URL on the server and watch the client keep working.
Quiz
Q1. What does REST stand for, and what kind of thing is it?
- Representational State Transfer — an architectural style for networked software
- Reliable Encrypted Server Transport — a security protocol
- Remote Execution of Server Tasks — a programming language
- Resource Exchange Standard Table — a data format
Show answer
Answer: A. Representational State Transfer — an architectural style for networked software
REST stands for Representational State Transfer, the architectural style Roy Fielding named in 2000. It is a set of design constraints — not a protocol, a format, or a piece of software — that a system usually applies on top of HTTP.
Q2. Which URL is the well-designed REST way to address a single user, and why?
- /getUser?id=1, because it says exactly what to do
- /users/1, because the address names the resource and the HTTP verb carries the action
- /user/fetch/1, because it lists the steps in order
- /deleteUser/1, because it names the operation and the target together
Show answer
Answer: B. /users/1, because the address names the resource and the HTTP verb carries the action
In REST the address is a noun that names the resource (/users/1), and the HTTP method (GET, DELETE, and so on) says what to do with it. Baking a verb into the path, like /getUser, throws away the predictability that is the whole point of REST.
Q3. You want to CREATE a new post. Which request is correct?
- PUT to the collection: PUT /posts with the new body
- POST to an item: POST /posts/1 with the body
- POST to the collection: POST /posts with the body
- GET the collection: GET /posts and read it
Show answer
Answer: C. POST to the collection: POST /posts with the body
Create maps to POST against the collection (/posts). The server assigns the new id and typically returns 201 Created with the new resource. You POST to the collection, not to an item, because the item does not exist yet.
Q4. Which HTTP verb corresponds to the "Read" operation in CRUD, and what property does it have?
- DELETE — it is safe and never changes anything
- POST — it is idempotent
- PATCH — it is safe but not idempotent
- GET — safe and idempotent, so cacheable
Show answer
Answer: D. GET — safe and idempotent, so cacheable
Read maps to GET, which is safe (it only reads and never changes server state) and idempotent. Because GET changes nothing, caches and clients can store and repeat it freely — the basis of REST caching.
Q5. Why must you be careful about blindly retrying a failed POST, but not a failed GET or DELETE?
- POST is not idempotent; GET and DELETE are
- POST requests are slower, so retrying wastes time
- POST requests cannot carry a body on the second attempt
- GET and DELETE are encrypted but POST is not
Show answer
Answer: A. POST is not idempotent; GET and DELETE are
POST is not idempotent: two identical POSTs may create two resources (for example, two orders and a double charge). GET is safe, and both GET and DELETE are idempotent, so repeating them leaves the server in the same state — which is why retry logic must know which verb it is retrying.
Q6. What is the difference between PUT and PATCH?
- PUT reads a resource; PATCH writes one
- PUT replaces the whole resource; PATCH only the fields sent
- PUT works on collections; PATCH works on items
- They are identical; the name is just a preference
Show answer
Answer: B. PUT replaces the whole resource; PATCH only the fields sent
PUT replaces the whole resource — omit a field and you may erase it — while PATCH merges only the fields you send, leaving the rest untouched. Use PATCH to change one attribute and PUT when you have the complete new version.
Q7. What does it mean that REST is "stateless," and why does it matter for scaling?
- The server saves your session so later requests are faster
- The server has no database and stores nothing at all
- Each request carries all it needs, so any server copy can answer
- Only one client can talk to the server at a time
Show answer
Answer: C. Each request carries all it needs, so any server copy can answer
Statelessness means every request is self-contained (identity travels in a token on each request) and the server remembers nothing between requests. That lets a provider run many identical copies behind a load balancer and send any request to any copy — the property that makes REST scale horizontally.
Q8. What is the difference between a resource and its representation?
- They are the same thing with two names
- A resource is the JSON; a representation is the URL
- A representation is stored on disk; a resource exists only in memory
- A resource is the thing; a representation is a JSON snapshot of it
Show answer
Answer: D. A resource is the thing; a representation is a JSON snapshot of it
The resource is the underlying thing (user 1); the representation is a document describing its current state — typically JSON — that the server sends you. The same resource can be represented as JSON, XML, or HTML; "Representational State Transfer" names exactly this exchange of representations.
Glossary
- REST
- Representational State Transfer — an architectural style for networked software that models a service as resources at addresses, acted on by a fixed set of standard verbs, with a stateless client-server exchange.
- resource
- Any thing a service exposes and names, such as a user, order, or post; the noun that a REST URL addresses.
- collection
- A resource that contains many others, addressed by a plural path such as /users; you create a new member by POSTing to it.
- endpoint
- A specific addressable URL through which a client acts on a resource, such as /users/1.
- CRUD
- The four basic operations on stored data — Create, Read, Update, Delete — which REST maps onto the HTTP verbs POST, GET, PUT/PATCH, and DELETE.
- stateless
- A design in which each request carries everything the server needs and the server keeps no memory of the client between requests, so any request can be handled by any server copy.
- representation
- A serialized snapshot of a resource's state that is transferred between client and server, most commonly as JSON; distinct from the resource itself.
- idempotent
- A property of a request such that making it many times leaves the server in the same state as making it once; GET, PUT, and DELETE are idempotent, while POST is not.
- safe
- A property of a request that only reads and never changes server state; GET is safe, which is why it can be cached and retried freely.
- HATEOAS
- Hypermedia As The Engine Of Application State — the REST constraint that a resource's representation includes links telling the client what it can do next and where.
- RPC
- Remote Procedure Call — an API style that models operations as named functions to invoke (e.g. createUser) rather than resources to act on; gRPC is a modern high-performance form.
- GraphQL
- An API style exposing a single endpoint where the client asks for exactly the fields it wants in one query, addressing REST's tendency toward many round trips or over- and under-fetching.
Sources and further reading
- Representational state transfer — Wikipedia (accessed 2026-07-12)
- What is REST — RESTful API (accessed 2026-07-12)
- HTTP request methods — MDN Web Docs (accessed 2026-07-12)
- Architectural Styles and the Design of Network-based Software Architectures (Ch. 5: REST) — Roy Fielding (accessed 2026-07-12)
- JSONPlaceholder — Guide — JSONPlaceholder (accessed 2026-07-12)
Kept in this browser, no account needed. Your progress page turns the whole record into one link you can bookmark or open on another device.