REST resources and verbs

Why it matters

Almost every app you will build talks to a server. A mobile app loads a user's feed, a web page saves a form, a dashboard pulls numbers. The server side of that conversation is an APIAn application programming interface: here, a set of URLs on a server that accept requests and send back data. (application programming interface): a set of URLs that accept requests and send back data. If the API is designed well, front-end and mobile developers can guess how it works before they read the docs. If it is designed badly, every screen needs special cases.

Most web APIs today follow a style called RESTA set of conventions on top of HTTP where URLs name resources and HTTP methods carry the action. (representational state transfer). REST is not a library or a standard you install. It is a set of conventions built on top of HTTP, the same protocol your browser uses to load pages.

The core idea: resources and verbs

REST splits every request into two parts:

• The resourceThe noun an API exposes, identified by a URL path such as /courses or /courses/42.: a noun, identified by a URL path. /courses, /courses/42, /courses/42/lessons.
• The verb: the HTTP method, which says what to do with that resource.

Two properties are worth remembering:

• SafeA safe method, such as GET, does not change data, so clients, caches and crawlers may call it freely. methods do not change data. GET is safe, so browsers, caches and crawlers may call it freely. Never let a GET delete or update anything.
• IdempotentAn idempotent method gives the same result when repeated: GET, PUT and DELETE are; POST is not. methods give the same result if you repeat them. GET, PUT and DELETE are idempotent: deleting item 42 twice leaves it just as deleted. POST is not: sending "create order" twice can create two orders. That is why payment APIs often ask for an idempotency key.

Worked example: designing routes for a resource

Say you are building the API for a course platform, and the first resource is a course. Start with the nouns, then attach verbs:

GET    /courses              list courses (maybe ?level=beginner&page=2)
POST   /courses              create a course (data in the request body)
GET    /courses/:id          read one course
PATCH  /courses/:id          change some fields of one course
DELETE /courses/:id          delete one course
GET    /courses/:id/lessons  list the lessons that belong to one course

A few habits make this predictable:

• Plural nouns for collections. /courses, not /course or /getCourses. The verb is already in the method, so do not repeat it in the path.
• IDs in the path, filters in the query stringThe part of a URL after ?, used for filters, sorting and paging, such as ?level=beginner&page=2.. /courses/42 names one thing. /courses?level=beginner narrows a list. Sorting and paging (?sort=title&page=2) also go in the query string.
• Nest only one level for ownership. /courses/42/lessons is clear. /schools/1/courses/42/lessons/7/comments is painful; once a lesson has its own ID, /lessons/7/comments works.
• Lowercase, hyphenated paths. /learning-paths, not /LearningPaths.

A full request and response look like this when you run curl -i against a local server:

GET /courses/42 HTTP/1.1
Host: localhost:3000
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{ "id": 42, "title": "Back-End Web APIs", "level": "intermediate" }

The request line holds the method and path. Headers carry metadata such as Accept (what format the client wants) and Content-Type (what format the body is in). The body holds the data. The response starts with a status code (200 OK here), which the next lesson covers in detail.

Actions that are not CRUD

Some operations do not fit create, read, update and delete neatly: "publish a course", "reset a password", "send a test email". Two common answers:

1. Model it as a field change: PATCH /courses/42 with { "status": "published" }.
2. Model it as creating a new resource: POST /password-resets with { "email": "..." }. The "reset request" becomes a thing you create.

Both are fine. What you should avoid is a path full of verbs such as POST /publishCourse?id=42, because each one becomes a special case for every client.

Common mistakes

• Using GET for changes. A link like /courses/42/delete can be triggered by a browser prefetch, a crawler or an image tag on another site.
• Verbs in paths. /createUser, /getAllUsers. Let the method carry the verb.
• Inconsistent shapes. If GET /courses returns { "items": [...] }, do not make GET /lessons return a bare array. Pick one shape and keep it.
• Leaking database details. The URL is a public contract. Exposing table names or internal columns makes it hard to change your database later.
• Changing a route that clients already use. Once a mobile app ships, old versions keep calling the old URL for months. Add new fields and routes; remove old ones slowly, or version the API (/v2/...).

Quick recap

• REST is a convention: resources are nouns in the URL, methods are verbs.
• GET reads and must never change data. POST creates, PUT replaces, PATCH updates part, DELETE removes.
• Use plural collections, IDs in the path, filters and paging in the query string, and shallow nesting.
• Your routes are a contract with every client. Keep them consistent and change them carefully.

Head to the Do tab and test yourself on route design before moving on to status codes.