REST API Design: Resources, Methods, Status Codes

Name resources as plural nouns, use GET, POST, PUT, PATCH and DELETE correctly, put data in the path, query, body or header, and return the right status code.

REST API design: common questions

What is the difference between PUT and PATCH?

PUT replaces the whole resource with what you send, so a missing field is wiped. PATCH changes only the fields you send. PUT is idempotent; PATCH usually is but not always.

When should a value go in the path vs the query string?

If the request means nothing without it, such as which event, put it in the path: /events/123. If it only filters, sorts or pages the result, put it in the query: /events?city=mumbai.

What is the difference between 401 and 403?

401 Unauthorized means the server does not know who you are (no or expired token). 403 Forbidden means it knows who you are but you are not allowed to do this.

Related chapters

Keep learning

Overview

Which event: event 123 It names the exact thing you want. Without it the request makes no sense, so it is part of the address: /events/123. Only show events in Mumbai It is an optional filter. /events works without it, so it goes after the ?: /events?city=mumbai. The seats you picked: A1 and A2 It is the data you are sending to create something. Bodies carry data for POST, PUT and PATCH. Your login token It is about who is asking, not what is asked, and it travels with every request: Authorization: Bearer … Show 20 results, page 2 Paging is optional and changes how a list is returned, so it goes in the query: ?limit=20&page=2. Which booking to cancel: booking 9 It picks the one thing to act on: DELETE /bookings/9. Lab: where does each piece of data go?

REST: resources, methods and passing data

REST is the default style for public APIs. You name the things in your system, give each one an address, and use a few standard verbs on them. This chapter builds the ticket site’s API step by step.

Start from the things, not the actions

In the last chapter we listed the entities of the ticket site: Event, Venue, Ticket, Booking. In REST each of these becomes a resource, which just means “a thing that has its own address”. The address is a URL path: Three naming habits make this easy to read: Nouns, not verbs Nest to show “belongs to” Action names (avoid) Resource names (use) GET /events/123POST /events/123/bookingsDELETE /bookings/9

The verbs: GET, POST, PUT, PATCH, DELETE

The path says which thing. The method (also called the HTTP verb) says what to do with it. There are five you need. The last column needs a word explained: an action is idempotent if doing it twice leaves things the same as doing it once. That matters because networks fail and apps retry. safe to repeat? read, change nothing GET /events/123 yes: reading twice changes nothing create something new POST /events/123/bookings no: twice makes two bookings replace the whole thing PUT /users/7 with the full profile yes: same profile saved twice change a few fields PATCH /users/7 with just the new email usually, not always remove it DELETE /bookings/9 yes: gone is still gone POST is the one that is not safe to repeat. If the “Book” request is sent twice, the user may pay twice. The idempotency chapter shows how to fix that with an idempotency key.

Where the data goes: path, query, body, header

A request has four places to put information. Here is one full booking request taken apart: Path/events/123/bookings: which thing. Required. Here: the bookings of event 123. Query?notify=true: optional extras after the ?. Filters, sorting, paging, flags. Leave it out and the request still works. HeaderAuthorization: …: facts about the request itself, like who is sending it and in what format. BodyThe JSON at the bottom: the data you are sending to create or change something. GET requests have no body. A simple test decides between path and query: if the request means nothing without it, it is path. If it only narrows or shapes the answer, it is query. Now try it yourself:

What comes back: status codes

Every response starts with a three-digit status code so the client knows what happened before reading the body. The first digit is the group: 2xx worked, 4xx the client sent something wrong, 5xx the server broke. You only need a handful: when, on the ticket site GET /events/123 found the event POST /events/123/bookings made a new booking Bad Request the body had no ticket_ids no login token, or it expired: “who are you?” logged in, but trying to cancel someone else’s booking Not Found event 999 does not exist seat A1 was booked by someone else a second ago Too Many Requests a bot sent 500 booking requests in a minute Internal Server Error a bug or the database is down

The whole ticket site API

Putting it together, this is all you would write on the whiteboard: That last point is a small detail interviewers like: never trust a user_id sent in the body. Take it from the login token. REST is the default, but it has a weak spot: one screen can need several requests. GraphQL was built for that. First, one level down: what HTTP itself promises, and what “RESTful” really means. Spotify uses GET, POST, PUT and DELETE exactly this way, and starting playback is a PUT that returns 204. Spotify’s methods and status codes

More courses

Jobs, linked to lessons — Browse jobs where every requirement links to the chapter that teaches it. See how ready you are, how long the gap takes to close, and which listings look stale.
Match a job post to courses — Paste a job post. Each skill is matched to a track here and put in learning order, foundations first.
React from open source with patterns — Patterns extracted from Material UI, Radix, React Aria, React Hook Form, Redux Toolkit, TanStack, and Next.js — not slides about hooks.
Database in depth — How a query becomes work. Indexes, isolation, locks, and the plans that explain why a page is slow — not an ORM tour.
Build a real API with NestJS — One ticket-booking API, built in order: a plain Node server first, then NestJS modules, validation, a real database, and the features real clients lean on.
Microservices — Microservice patterns one diagram at a time: how to split a monolith, how services talk, and how data stays consistent without distributed transactions.
Kafka — A beginner-to-senior path through event logs, reliable delivery, production operations, and disaster recovery.
AI engineering for software engineers — Eight free reads, in order, for software engineers moving into AI: when to build an agent, how to build one, how to test it, and how the model works underneath.
Frontend system design — How a UI is sliced when it is a product, not a page: ownership of state, cache, routes, and what happens when the network lies.
TypeScript in depth — The type system as a design tool. Inference, narrowing, generics, and the errors that mean the model is wrong — not a catalog of utility types.
CSS in depth — See the box, then the page. Visual chapters from the box model through Flexbox surprises, Grid, selectors, and units, then backgrounds, shapes, and visual effects, each with a playground.
Accessibility — Foundations first (WCAG in plain words, semantic HTML, lists, alt text), then hands-on HTML labs, a full pass of WAI-ARIA 1.3, and a final fix-the-page challenge.
Docker — What an image is, why layers cache, and how containers find each other on a network.
Redis — Fifteen Redis patterns, one picture each: cache, session, lock, counter, rate limiter, queue, and when Redis is the wrong tool.
Kubernetes — Kubernetes from zero to operators: why it exists, Pods, Deployments and Services, then configuration, networking, storage, scheduling, scaling and security.