Skip to content
Ameen Abozaid
Englishالعربية
PublishedBEG-053-L02

REST in plain language

  • Lesson 2 of 6
  • 10 min read
  • Beginner
On This Lesson 11 topics

Lesson Overview

Last lesson you learned that an API is a menu. This lesson is about how to write a good menu for web APIs. The most popular style is called REST. You do not need the theory behind it to use it well. You need one habit: name the things (resources) with nouns in the URL, and let the HTTP method be the verb.

In the restaurant picture, think of a menu organized by dishes ("Soups", "Salads") instead of by instructions ("Go-get-me-the-soups", "Please-make-a-salad"). The dish names stay the same; what changes is what you do with them: look at one, order one, send one back.

By the end you will be able to turn a messy URL like /getBooks into a clean one, and you will know which method and status code go with each action.

This lesson builds on Lesson 1 (APIs, client, and provider) and on Module BEG-052 (methods, status codes, JSON, URLs).

Learning Objectives

By the end of this lesson you will be able to:

  • Explain the REST idea of a resource and a representation.
  • Write collection URLs and item URLs using plural nouns.
  • Match each CRUD action to an HTTP method.
  • Choose sensible status codes for the common outcomes (200, 201, 204, 404).
  • Spot and fix verbs in URLs.
  • Express a nested relationship such as "the loans of one member" in a URL.

Written Explanation

What REST is

REST stands for Representational State Transfer. The MDN glossary describes it as a group of architecture constraints for building efficient, reliable, and scalable distributed systems. The core idea there is that a resource, such as a document, is transferred through standard, language-independent client/server interactions. MDN also notes that people use "RESTful" loosely for any HTTP API, even when it does not follow every REST rule, and suggests that beginners think of a REST API as an HTTP service that normal web tools can call. That is how we will use the word in this course: a web API designed around resources, URLs, and HTTP methods.

Resources

A resource is a thing the API is about: a book, a member, a loan. HTTP itself puts no limit on what a resource can be; the RFC that defines HTTP semantics (RFC 9110) says it only defines a standard interface for interacting with resources, which are usually identified by URIs.

When you ask for a resource, you do not get the thing itself. You get a representation: a snapshot of its current state in a format that can travel, usually JSON. For a book that is a JSON object with title, author, and so on. The database row stays in the kitchen.

Nouns in URLs, plural

Each resource type gets a collection URL, and each item gets an item URL:

URLMeaning
/booksThe collection: all books
/books/7One item: the book with id 7
/members/3/loansA sub-collection: the loans that belong to member 3

Rules of thumb:

  • Use nouns, never verbs: /books, not /getBooks.
  • Use plural names for collections: /books, not /book. Then /books/7 reads as "book 7 of the books".
  • Put the id in the path for one item: /books/7.
  • Use lower case and hyphens, keep it short and predictable.
  • Nest only to show ownership, and not deeper than needed: /members/3/loans is fine; five levels is hard to read.

These are conventions, not laws. They exist so that someone who has never seen your API can guess your URLs.

The method is the verb

If the URL names the thing, who says what to do with it? The HTTP method (Module BEG-052). The MDN methods reference summarizes them like this:

MethodWhat it doesSafeIdempotent
GETGets a representation of the resource; should only readyesyes
POSTSubmits data to a resource, often changing server state (such as creating)nono
PUTReplaces the whole resource with the request bodynoyes
DELETEDeletes the resourcenoyes

Safe means the request is not expected to change server state. Idempotent means sending the same request twice has the same effect as sending it once. Remember it like this: sending DELETE /books/7 twice still leaves book 7 deleted, but sending POST /books twice may create two books.

Combine the noun and the verb and you get the standard map for a resource:

ActionRequestTypical success status
List allGET /books200 OK
Read oneGET /books/7200 OK
CreatePOST /books201 Created
ReplacePUT /books/7200 OK
RemoveDELETE /books/7204 No Content (or 200)

(PATCH, from Module BEG-052, updates only some fields. We keep it out of the table to stay focused.)

Status codes tell the result

The method says what you tried; the status code says how it went. Three you will use constantly:

  • 201 Created. MDN says it means a new resource was created, most often in answer to a POST. The new resource must be reachable at the request URL or at the URL in a Location header.
  • 204 No Content. The request succeeded and there is nothing to send back. After a DELETE it means "deleted, nothing more to say". A 204 response has no body.
  • 404 Not Found. The server cannot find the resource you asked for: a mistyped path, or an item that does not exist. It says nothing about whether the absence is temporary.

Alongside them: 200 for a successful read or update, 400 (bad request) when the client sent something invalid, and 5xx when the server itself failed. Never return 200 with an error hidden in the body: clients and tools read the status code first.

Query parameters filter and shape

Do not invent a new URL for every question. The collection URL plus query parameters (Module BEG-052) answers many: /books?author=herbert filters, and /books?limit=10 limits the size. Details are the provider's choice and are written in its documentation. We come back to this in Lesson 5.

Verbs in URLs: the mistake to avoid

MessyClean
GET /getBooksGET /books
POST /createMemberPOST /members
GET /book/delete/7DELETE /books/7
POST /books/7/updatePUT /books/7

The messy versions repeat the verb the method already says, and they invite inconsistent names (getBooks, fetchMembers, listLoans). With nouns plus methods, one learned pattern covers every resource. A safety bonus: a link like GET /book/delete/7 could be triggered by a browser prefetch or a crawler, because GET is supposed to be safe.

Examples

Example 1: Simple. Fixing URLs

A teacher wrote this API menu for a school: /getStudents, /addStudent, /student/remove/12.

Clean version:

text
GET    /students
POST   /students
DELETE /students/12

Same three abilities, one noun, three methods.

Example 2: Practical. A real list and a real single item

DummyJSON (a public practice API) follows the pattern. Its documentation lists GET /products and GET /products/{id}. We shorten answers with limit and select, parameters that this API's docs define.

bash
curl -s "https://dummyjson.com/products?limit=2&select=title,price"
curl -s "https://dummyjson.com/products/1?select=title,price"

Real output:

json
{"products":[{"id":1,"title":"Essence Mascara Lash Princess","price":9.99},{"id":2,"title":"Eyeshadow Palette with Mirror","price":19.99}],"total":194,"skip":0,"limit":2}
{"id":1,"title":"Essence Mascara Lash Princess","price":9.99}

The collection answer wraps its items in an object with products, total, skip, and limit: this API's own choice. The single item is just the object. APIs differ in such details, which is why you read documentation.

Example 3: Realistic. A library, with relationships

A library has books, members, and loans. A member borrows books.

text
GET    /members                list members              200
POST   /members                create a member           201 (or 400)
GET    /members/3              read member 3             200 (or 404)
GET    /members/3/loans        loans of member 3         200 (or 404)
DELETE /loans/55               remove loan 55            204 (or 404)

Why is /members/3/loans nested but DELETE /loans/55 is not? Loan 55 already has a unique id, so its own URL is enough. The nested URL is used where the relationship is the question: "whose loans?".

Backend Insight

In a Java backend, each resource usually becomes a small group of classes (you will build this later in the roadmap), and each URL plus method is wired to one piece of code. A consistent URL scheme makes that wiring predictable, and it makes the API self-explanatory to other developers and to tools. When a teammate asks "how do I get the loans of a member?", the answer should be guessable, not looked up.

Remember also that the method's meaning is a promise: a GET that deletes data breaks tools, caches, and crawlers. Keep reads as reads.

Common Mistakes

  • Verbs in URLs (/getBooks, /createMember). The method is the verb.
  • Singular and plural mixed (/book and /members). Pick plural and keep it.
  • Using GET for actions that change data. GET must only read.
  • Always answering 200. Use 201 for creation, 204 or 200 for delete, 404 for missing, 400 for bad input.
  • Treating REST as a strict law. These are conventions. When an API breaks one, trust its documentation.
  • Deep nesting, like /libraries/1/members/3/loans/5/books/9. Give inner things their own top-level URLs.

Exercises

Level A: Foundation

  1. A pet shelter has animals and adopters. Write the collection URL and an item URL for each.
  2. Fix these: GET /listAnimals, POST /newAdopter, GET /animal/delete/4.
  3. Which method and which success status match "create a new adopter"?

Level B: Application

  1. Complete the table for the resource animals: list, read one, create, replace, delete. Give method, URL, and a success status for each.
  2. Write the URL for "the adoptions of adopter 9".
  3. Run curl -s "https://dummyjson.com/products/2?select=title" and curl -s "https://dummyjson.com/products/1?select=title". In a sentence, say what the two requests have in common and what differs.

Level C: Challenge

  1. A teammate says: "Our DELETE /books/7 returns 404 the second time. That is wrong; it should be 204 again." Is the teammate right? Argue both sides briefly, and name the idempotent idea.
  2. Design the URLs for a school with students, courses, and enrollments (a student enrolls in courses). Include "the courses of student 5" and "create an enrollment". Avoid verbs and avoid nesting deeper than two levels.
Show solutions
  1. /animals and /animals/4; /adopters and /adopters/9.
  2. GET /animals, POST /adopters, DELETE /animals/4.
  3. POST /adopters, success status 201 Created.
  4. GET /animals 200; GET /animals/{id} 200; POST /animals 201; PUT /animals/{id} 200; DELETE /animals/{id} 204 (200 is also seen).
  5. /adopters/9/adoptions.
  6. Both use GET on the same collection (/products) and ask for one item and only its title; they differ only in the id (2 or 1), so the answers are different products: {"id":2,"title":"Eyeshadow Palette with Mirror"} and {"id":1,"title":"Essence Mascara Lash Princess"} (real output at the time of writing).
  7. Both views are defensible. Idempotent means the effect on the server is the same after one or many calls: book 7 is gone either way. It does not require the same status code. A second DELETE finds nothing, so 404 is honest; a provider who wants a simpler client may return 204 again. The important thing is to document the choice and keep it consistent.
  8. For example: GET /students, GET /students/5, GET /courses, GET /courses/12, GET /students/5/enrollments (or /students/5/courses), POST /enrollments with studentId and courseId in the body. Enrollments get their own top-level URL, so nesting never goes beyond two levels.

Mini Challenge

Choose a small domain you know (a gym, a cinema, a clinic). Name three resources. For one of them, write the full five-line map (list, read one, create, replace, delete) with methods, URLs, and success statuses, plus one query parameter that would be useful for filtering the list. Check that no URL contains a verb.

Summary & Next Lesson

Key takeaways

  • REST, in this course, means a web API designed around resources, URLs, and methods.
  • A resource is a thing; you receive a representation of it (usually JSON).
  • URLs are plural nouns: /books, /books/7, /members/3/loans.
  • The method is the verb: GET read, POST create, PUT replace, DELETE remove.
  • Status codes report the result: 200, 201, 204, 400, 404.
  • Never put verbs in URLs. Filter with query parameters.

Next lesson

In "Postman tour" you will install a friendly tool that sends these requests for you and shows responses, so you can try every table from this lesson on a real API.

Self-check

  1. What is the difference between a resource and a representation?
  2. Fix /deleteBook?id=7.
  3. Which status goes with a successful POST that creates something?
  4. Why are collection URLs plural?
  5. Which is safe: GET or DELETE?
Show answers
  1. The resource is the thing; the representation is a snapshot of its state in a format that can travel, usually JSON.
  2. DELETE /books/7.
  3. 201 Created.
  4. So /books reads as the whole collection and /books/7 as one item of it; one consistent pattern.
  5. GET.

References

  • Mozilla Developer Network, REST (glossary). Defines REST as architecture constraints and notes the loose use of "RESTful".
  • IETF, RFC 9110: HTTP Semantics. Used for the ideas of resource, URI, and representation (only the opening sections about resources were read).
  • Mozilla Developer Network, HTTP request methods. Supports the safe/idempotent table for GET, POST, PUT, DELETE.
  • Mozilla Developer Network, 201 Created, 204 No Content, and 404 Not Found. Support the meaning of each status code.
  • DummyJSON, Products documentation. Documents the list, single, limit, and select features; output shown was produced by running the commands.
  • Conventions such as plural nouns, nesting depth, and "keep reads as reads" are widely used design advice and this course's own teaching choices, not rules from a standard; the idempotency discussion of a second DELETE follows the MDN methods page, which says the response may differ.

Practice

Apply this lesson with the module's lab, exercises and quiz.

Lab and exercises Quiz

Marking a lesson complete is optional and you can undo it any time. Your progress stays in this browser.

Continue to next lesson

Type to search levels, phases, modules and lessons.