Computing Foundations › APIs and the Web › Day 23

Day 23: REST Fundamentals: Resources and Verbs

Day 23 of 365 — 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.

Course
Computing Foundations
Category
APIs and the Web
Reading time
≈ 40 min
Practical time
≈ 30 min
Lesson duration
1h 10m
Last verified
2026-07-12

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

  1. 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
  2. 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
  3. 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.
  4. 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:

Prerequisites

Why this matters


The idea in plain language

Diagram: verb-based paths compared with resource-based paths


Historical background


What it is — and what it is not

It is:

It is not:


Why it was created and what problems it solves


How it works

Resources, collections, and items

Diagram: which HTTP methods act on collections and which act on items

Architecture diagram: the collection /users and the item /users/1, with the four verbs GET, POST, PUT/PATCH, and DELETE acting on them

The verbs, mapped to CRUD

Diagram: a PUT request compared with a PATCH request

OperationVerbTargetWhat it doesSuccess
ReadGETcollection or itemFetch a representation; change nothing200
CreatePOSTcollectionAdd an item; the server assigns the id201
Update (replace)PUTitemReplace it entirely with your body200/204
Update (partial)PATCHitemChange only the fields you sent200
DeleteDELETEitemRemove it200/204

Flow diagram: the CRUD operations Create, Read, Update, and Delete mapped to the HTTP methods POST, GET, PUT and PATCH, and DELETE

Statelessness

Diagram: how statelessness allows any server to answer any request

Representations

{
  "id": 1,
  "name": "Ada Lovelace",
  "email": "ada@example.org",
  "role": "admin"
}

Safety and idempotency

Diagram: which HTTP verbs are safe to retry after a timeout

VerbSafe?Idempotent?Consequence
GETYesYesCache and retry freely
POSTNoNoTwo identical calls may create two resources
PUTNoYesReplacing twice equals replacing once
PATCHNoUsually noA relative change applied twice differs
DELETENoYesDeleting a deleted item leaves it deleted

HATEOAS at a glance

Diagram: a client following hypermedia links compared with one building URLs

{
  "id": 1,
  "name": "Ada Lovelace",
  "_links": {
    "self":   { "href": "/users/1" },
    "orders": { "href": "/users/1/orders" },
    "edit":   { "href": "/users/1", "method": "PUT" }
  }
}

An everyday analogy

Diagram: the expected status codes for each REST verb

A library catalogue.

The libraryREST
The shelf of all fictionA collection, /books
One book with a numberAn item, /books/1
Its section, then its shelf, then the bookNested paths
Read itGET
Add a new one to the shelfPOST to the collection
Replace a damaged copyPUT on the item
Correct one field on its cardPATCH
Withdraw itDELETE

Examples in practice

Diagram: REST collections compared with items, and which verb belongs where


Implications: security, privacy, performance, scalability, and cost

Diagram: checking authentication compared with checking ownership


Alternatives: free, open source, and commercial

Diagram: REST compared with GraphQL

StyleTypeWhere it fits
RESTThe defaultResource-shaped data, public APIs, anything cacheable
GraphQLFree, open sourceClients that need to choose their own response shape
gRPCFree, open sourceService-to-service, where speed beats readability
JSON-RPCFree, open sourceGenuinely operation-shaped work that is not CRUD
OpenAPIFree, open sourceNot an alternative — how you describe a REST API formally
WebhooksThe inverseEvents pushed to you, rather than polled — Day 26

TermWhat it actually is
ResourceA thing the API names
CollectionA resource holding many others
ItemOne member of a collection
RepresentationA serialised snapshot of a resource’s state
CRUDCreate, read, update, delete
StatelessnessThe server remembers nothing between requests
HATEOASResponses carry links to what you can do next

When to use it — and when not to

Diagram: an endpoint per variation compared with query parameters on one collection


The AI connection


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 doingCommand
Read a collectioncurl 'https://jsonplaceholder.typicode.com/posts?_limit=3'
Read one itemcurl https://jsonplaceholder.typicode.com/posts/1
Createcurl -i -X POST -H 'Content-Type: application/json' -d '{"title":"hi","userId":1}' .../posts
Replacecurl -i -X PUT -H 'Content-Type: application/json' -d '{"id":1,"title":"new","userId":1}' .../posts/1
Mergecurl -i -X PATCH -H 'Content-Type: application/json' -d '{"title":"just this"}' .../posts/1
Deletecurl -i -X DELETE .../posts/1
Nested collectioncurl '.../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}

Validate your work

Troubleshooting

Common mistakes


Practice assignment


Extension challenge


Quiz

Q1. What does REST stand for, and what kind of thing is it?

  1. Representational State Transfer — an architectural style for networked software
  2. Reliable Encrypted Server Transport — a security protocol
  3. Remote Execution of Server Tasks — a programming language
  4. 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?

  1. /getUser?id=1, because it says exactly what to do
  2. /users/1, because the address names the resource and the HTTP verb carries the action
  3. /user/fetch/1, because it lists the steps in order
  4. /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?

  1. PUT to the collection: PUT /posts with the new body
  2. POST to an item: POST /posts/1 with the body
  3. POST to the collection: POST /posts with the body
  4. 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?

  1. DELETE — it is safe and never changes anything
  2. POST — it is idempotent
  3. PATCH — it is safe but not idempotent
  4. 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?

  1. POST is not idempotent; GET and DELETE are
  2. POST requests are slower, so retrying wastes time
  3. POST requests cannot carry a body on the second attempt
  4. 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?

  1. PUT reads a resource; PATCH writes one
  2. PUT replaces the whole resource; PATCH only the fields sent
  3. PUT works on collections; PATCH works on items
  4. 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?

  1. The server saves your session so later requests are faster
  2. The server has no database and stores nothing at all
  3. Each request carries all it needs, so any server copy can answer
  4. 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?

  1. They are the same thing with two names
  2. A resource is the JSON; a representation is the URL
  3. A representation is stored on disk; a resource exists only in memory
  4. 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


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.