Designing REST Endpoints: Create, Update and Delete
A REST API names each kind of thing it holds with a plural noun, such as /tickets, and lets the HTTP method be the verb, so POST answers 201 with the new item, PUT replaces an item, PATCH changes part of it, and DELETE answers 204 with no body.
Journeyman · Node.js · REST API · Updated
After this lesson you can
- Design a resource's endpoints with plural nouns in the path and the HTTP method as the verb
- Choose the method and status code for creating, replacing, changing and deleting, such as POST and 201 or DELETE and 204
- Write POST, PUT, PATCH and DELETE routes in Express that answer with the right status and body
Key takeaways
- A resource is a kind of thing an API holds, such as repair tickets. Its paths are plural nouns, /tickets for all of them and /tickets/3 for one, and the method says what to do.
- POST /tickets creates a ticket and answers 201 Created with the new ticket, its id included, because the server chose the id.
- PUT replaces the whole ticket with the body, so a field the body leaves out is gone. PATCH changes only the fields the body sends.
- DELETE answers 204 No Content, with no body. Deleting the same ticket a second time answers 404.
- A GET only reads. Browsers, link previews and search engines follow GET links by themselves, so a GET that changes data will change it by accident.
Every API you build will be called by code someone else writes: a phone app, a web page, another team's service. They'll guess your addresses, and once they're in use, changing them breaks those callers. A few naming rules make an API people can guess, and they're the rules nearly every public API follows, from online shops to maps to payments.
Spoke & Chain Bike Repair, a neighborhood bike shop, keeps its work tickets on a clipboard: who brought the bike in, which bike, what's wrong, and where it is (waiting, in repair, ready or picked up). The shop's first try at an API named every address after an action:
GET /getAllTickets
POST /newTicket
POST /changeTicketStatus
GET /removeTicket?id=4
It works, but every new action needs a new name, and nobody can guess the next one: is it /editTicket or /updateTicket? The last line is a trap, too. Everything on the internet treats a GET as reading only, so browsers can fetch links ahead of time, chat apps open them to show a preview, and search engines follow them. Paste that link in the shop's group chat, and ticket 4 can be gone before anyone clicks it.
Resources are nouns, methods are verbs
Think of the shop's clipboard. Adding a ticket and crossing one off don't need two clipboards: there's one clipboard, and what you do to it changes. REST (short for representational state transfer) is the style most web APIs follow, and it works the same way. Each kind of thing the API holds is a resource, named by a plural noun: /tickets for the whole clipboard, /tickets/3 for ticket 3. The HTTP method is the verb. Six endpoints cover everything the shop does with tickets:
| Method and path | What it does | The answer when it works |
|---|---|---|
GET /tickets |
Lists every ticket | 200 OK and the list |
GET /tickets/3 |
Reads ticket 3 | 200 OK and the ticket |
POST /tickets |
Adds a new ticket | 201 Created and the new ticket |
PUT /tickets/3 |
Replaces ticket 3 with the body | 200 OK and the ticket |
PATCH /tickets/3 |
Changes part of ticket 3 | 200 OK and the ticket |
DELETE /tickets/3 |
Removes ticket 3 | 204 No Content, no body |
The path stays plural for one item, so /tickets/3 reads as "ticket 3 of the tickets", and every route with an id answers 404 when there's no such ticket. A new action rarely needs a new path: marking a bike ready is PATCH /tickets/3 with { "status": "ready" }.
POST creates, and answers 201
The client sends what it knows (who, which bike, what's wrong), and the server fills in the rest: the next id, and a status of waiting. In an app.js with express.json(), as in Your First Express App: Routes and JSON:
const tickets = [
{ id: 1, customer: "Dana", bike: "blue cruiser", problem: "flat rear tire", status: "waiting" },
{ id: 2, customer: "Marco", bike: "red road bike", problem: "brakes squeal", status: "in repair" },
{ id: 3, customer: "Ana", bike: "green hybrid", problem: "chain keeps slipping", status: "ready" },
];
let nextId = 4;
app.post("/tickets", (req, res) => {
const ticket = {
id: nextId,
customer: req.body.customer,
bike: req.body.bike,
problem: req.body.problem,
status: "waiting",
};
nextId = nextId + 1;
tickets.push(ticket);
res.status(201).json(ticket);
});
Lena brings in her folding bike. The request, then the answer's status line and body:
POST /tickets { "customer": "Lena", "bike": "folding bike", "problem": "gears won't shift" }
HTTP/1.1 201 Created
{"id":4,"customer":"Lena","bike":"folding bike","problem":"gears won't shift","status":"waiting"}
201 Created says "done: I made it", and the body is the whole new ticket. The id matters most: the client didn't choose it, so this is how it learns where the ticket lives.
PUT replaces, PATCH changes part
The shop's paper tickets can be changed two ways: tear one up and fill in a fresh form, or cross out one line and write the new value. PUT is the fresh form: the body is the new ticket. PATCH is the crossed-out line: only the fields the body sends change.

app.put("/tickets/:id", (req, res) => {
const ticket = tickets.find((t) => t.id === Number(req.params.id));
if (ticket === undefined) {
res.status(404).json({ message: `There's no ticket ${req.params.id}.` });
return;
}
ticket.customer = req.body.customer;
ticket.bike = req.body.bike;
ticket.problem = req.body.problem;
ticket.status = req.body.status;
res.json(ticket);
});
app.patch("/tickets/:id", (req, res) => {
const ticket = tickets.find((t) => t.id === Number(req.params.id));
if (ticket === undefined) {
res.status(404).json({ message: `There's no ticket ${req.params.id}.` });
return;
}
for (const field of ["customer", "bike", "problem", "status"]) {
if (req.body[field] !== undefined) {
ticket[field] = req.body[field];
}
}
res.json(ticket);
});
The for...of loop goes through the four field names, and req.body[field] reads the field with that name, so only the fields that were sent are copied. A field that isn't in the list, such as id, can't be changed at all. Send each one a body with some fields left out:
PUT /tickets/3 { "customer": "Ana", "bike": "green hybrid" }
HTTP/1.1 200 OK
{"id":3,"customer":"Ana","bike":"green hybrid"}
PATCH /tickets/2 { "status": "ready" }
HTTP/1.1 200 OK
{"id":2,"customer":"Marco","bike":"red road bike","problem":"brakes squeal","status":"ready"}
The PUT left out problem and status, so ticket 3 lost them: a field set to undefined doesn't appear in JSON at all. That's PUT working as designed. Most everyday changes are PATCHes; a PUT is for a client that holds the whole item and means to replace it.
DELETE answers 204
Removing a ticket has nothing to send back, so the answer is 204 No Content. res.status(204).end() finishes the response with no body:
app.delete("/tickets/:id", (req, res) => {
const index = tickets.findIndex((t) => t.id === Number(req.params.id));
if (index === -1) {
res.status(404).json({ message: `There's no ticket ${req.params.id}.` });
return;
}
tickets.splice(index, 1);
res.status(204).end();
});
findIndex gives the ticket's position, or -1 when there's none, and splice(index, 1) removes one item at that position. Deleting ticket 1 twice:
DELETE /tickets/1
HTTP/1.1 204 No Content
DELETE /tickets/1
HTTP/1.1 404 Not Found
{"message":"There's no ticket 1."}
The second DELETE finds nothing at that address, so it's a 404. These routes still trust whatever body arrives (Lena could send {} and get a ticket with no customer), which Checking Input by Hand fixes next. Their error bodies are { "message": … } for now; Error Handling and Consistent Error Responses gives the whole API one error shape.
Check yourself
2 questions to try on the lesson page.
So what
Nouns for paths, methods for verbs, and the right status for each action make an API that strangers can guess, and a GET that only reads means no link preview will ever delete a ticket.