Full-Stack Development · Tutorial 11 of 11
API Design Basics: endpoints, status codes and versioning
By the FUTEAC Team · 18 November 2026 · 14 min read · Beginner
In short
Good API design is mostly naming and honesty. Use plural nouns for resources, one HTTP method per action, and the right status code for every outcome: 201 when something is created, 404 when it is missing, 400 when the request is wrong. Version the URL as /api/v1/. This tutorial builds a small books API and runs every request.
- Endpoints are nouns, not verbs.
/booksnames a thing; the HTTP method says what to do with it. - The status code is the answer. A client should know if a request worked without reading the body.
- Version in the URL.
/api/v1/bookslets version 2 exist without breaking version 1. - Page every list. A list endpoint without pagination returns the whole table one day, and that day it falls over.
- This tutorial feeds the Node & Express API Foundations course (/course/node-express-api-foundations) and the API Design (/skill/api-design) skill.
Before you start
What does a good endpoint look like?
An endpoint is an address, and a good address can be guessed. Think of a restaurant menu: the dish names are nouns, and you tell the waiter what to do with them. An API works the same way. The URL names the thing, and the HTTP method says the action.
| Rule | Good | Bad |
|---|---|---|
| Plural nouns for collections | /books | /book, /getBooks |
| One id for one item | /books/2 | /books?id=2 for a single book |
| Nest only one level deep | /authors/1/books | /authors/1/books/2/reviews/3 |
| No verbs in the URL | POST /books | POST /createBook |
| Lowercase, hyphens for spaces | /blog-posts | /BlogPosts, /blog_posts |
POST /createBook is the mistake to unlearn first. The verb already lives in the method: POST means create. Saying it twice is how APIs end up with /getBooks, /deleteBook/2 and /updateBookInfo, three spellings of the same idea. One resource, one URL, five methods.
Which HTTP method does what?
Five methods cover nearly every API a beginner builds. The rule is simple: GET reads, POST creates, PUT replaces, PATCH changes part, DELETE removes.
| Method | Route | What it does | Success status |
|---|---|---|---|
| GET | /api/v1/books | List books | 200 OK |
| GET | /api/v1/books/2 | Read one book | 200 OK |
| POST | /api/v1/books | Create a book | 201 Created |
| PUT | /api/v1/books/4 | Replace a whole book | 200 OK |
| PATCH | /api/v1/books/4 | Change some fields | 200 OK |
| DELETE | /api/v1/books/4 | Remove a book | 204 No Content |
PUT and PATCH are the pair beginners mix up. PUT sends the whole book again, every field, even the ones that did not change. PATCH sends only the fields that changed, like just the year. If a client PUTs a book without the author field, the author is gone, because PUT means "this is the whole thing now". Use PATCH for edits in a form, and keep PUT for full replacements.
GET requests are safe to repeat: reading the same book twice changes nothing. POST is not: sending the same create request twice creates two books. That is why a form that double-submits is a real bug, and why the browser warns you before resubmitting a POST.
Which status code do I send?
The status code is the first thing a client reads, and often the only thing. A frontend checks it before it touches the body, so a wrong code is worse than a wrong message: the body can be perfect and the client still does the wrong thing.
| Code | Meaning | Send it when |
|---|---|---|
| 200 OK | It worked, here is the result | GET, PUT and PATCH succeed |
| 201 Created | Something new exists now | POST created a book; include a Location header pointing at it |
| 204 No Content | It worked, there is nothing to send back | DELETE succeeded |
| 400 Bad Request | The request itself is wrong | A required field is missing, or a value fails validation |
| 404 Not Found | That thing does not exist | The id in the URL matches no book |
| 405 Method Not Allowed | The route exists, the method does not | Someone POSTs to /books/2, which only accepts GET, PUT, PATCH and DELETE |
| 500 Internal Server Error | Something broke on your side | The database is down, or your code threw an error |
Two habits keep this table honest. First, 404 means the resource is missing, not that the route is wrong: a request for book 99 is a 404, and a request for /magazines is also a 404, but with a different error code in the body so the client can tell them apart. Second, never send 200 for an error and never send 500 for a client's mistake. A missing field is the client's fault, so it is a 400; a dead database is your fault, so it is a 500.
How do I version an API?
Put the version in the URL: /api/v1/books. It is the dullest option and the one that works. The day you change the shape of a book, say by renaming author to authors, every client built against version 1 keeps working, because version 1 still answers at the same address. Version 2 lives at /api/v2/books, and clients move over when they are ready.
The alternative beginners reach for is no version at all, which means every change is a breaking change, or versioning by a header, which hides the version where nobody can see it in a browser or a curl command. A URL version is visible, bookmarkable and testable. One rule: never change what version 1 returns. Fix bugs in it, but do not rename its fields. Version 1 is a promise.
How do I list lots of things?
A list endpoint without pagination works until the table grows, then it returns ten thousand rows in one response and the page hangs. Page from the start, with page and limit as query strings, and tell the client how many pages there are.
GET /api/v1/books?page=1&limit=2{
"data": [
{"id": 1, "title": "The Hobbit", "author": "J.R.R. Tolkien", "year": 1937},
{"id": 2, "title": "Dune", "author": "Frank Herbert", "year": 1965}
],
"page": 1,
"limit": 2,
"total": 3,
"totalPages": 2
}The shape matters as much as the paging. The books sit under data, and page, limit, total and totalPages sit beside them, so a client can draw "Page 1 of 2" without counting. Set a maximum limit on the server, 50 in the example below, so ?limit=100000 cannot ask for the whole table. Page 2 returns the one remaining book, Neuromancer, and totalPages stays 2.
What does a good error look like?
Every error in this API has the same shape, so a client writes one error handler instead of one per endpoint.
{"error": {"code": "book_not_found", "message": "No book with that id exists."}}The code is for machines: short, stable, lowercase with underscores, the same every time this error happens, so the client can switch on it. The message is for humans: plain words that say what went wrong. Keep the message free of stack traces and database errors; those go in your server log, not in the response. And the status code travels with the body: this error arrives as a 404, not a 200, which is the subject of the wrong turn in section 8.
The worked example: a books API, run end to end
Here is the whole API, in one file. The books live in an array that stands in for the books table from item 57. Run it with node server.js, then try each request below with curl.
const express = require("express");
const app = express();
app.use(express.json());
let books = [
{ id: 1, title: "The Hobbit", author: "J.R.R. Tolkien", year: 1937 },
{ id: 2, title: "Dune", author: "Frank Herbert", year: 1965 },
{ id: 3, title: "Neuromancer", author: "William Gibson", year: 1984 },
];
let nextId = 4;
const error = (res, status, code, message) =>
res.status(status).json({ error: { code, message } });
app.get("/api/v1/books", (req, res) => {
const page = Math.max(1, parseInt(req.query.page, 10) || 1);
const limit = Math.min(50, Math.max(1, parseInt(req.query.limit, 10) || 10));
const start = (page - 1) * limit;
const items = books.slice(start, start + limit);
res.json({
data: items,
page,
limit,
total: books.length,
totalPages: Math.ceil(books.length / limit),
});
});
app.get("/api/v1/books/:id", (req, res) => {
const book = books.find((b) => b.id === Number(req.params.id));
if (!book) return error(res, 404, "book_not_found", "No book with that id exists.");
res.json({ data: book });
});
app.post("/api/v1/books", (req, res) => {
const { title, author, year } = req.body;
if (!title || !author) {
return error(res, 400, "missing_fields", "Both title and author are required.");
}
const book = { id: nextId++, title, author, year: year ?? null };
books.push(book);
res.status(201).location(`/api/v1/books/${book.id}`).json({ data: book });
});
app.put("/api/v1/books/:id", (req, res) => {
const book = books.find((b) => b.id === Number(req.params.id));
if (!book) return error(res, 404, "book_not_found", "No book with that id exists.");
const { title, author, year } = req.body;
if (!title || !author) {
return error(res, 400, "missing_fields", "Both title and author are required.");
}
Object.assign(book, { title, author, year: year ?? null });
res.json({ data: book });
});
app.patch("/api/v1/books/:id", (req, res) => {
const book = books.find((b) => b.id === Number(req.params.id));
if (!book) return error(res, 404, "book_not_found", "No book with that id exists.");
Object.assign(book, req.body);
res.json({ data: book });
});
app.delete("/api/v1/books/:id", (req, res) => {
const index = books.findIndex((b) => b.id === Number(req.params.id));
if (index === -1) return error(res, 404, "book_not_found", "No book with that id exists.");
books.splice(index, 1);
res.status(204).send();
});
app.use("/api/v1", (req, res) =>
error(res, 404, "route_not_found", "That endpoint does not exist under /api/v1.")
);
app.listen(3000, () => console.log("Books API listening on http://localhost:3000"));Every request below was run against this server, and the status and body shown are the real ones.
List page 1, two per page:
curl "http://localhost:3000/api/v1/books?page=1&limit=2"HTTP/1.1 200 OK
{"data":[{"id":1,"title":"The Hobbit","author":"J.R.R. Tolkien","year":1937},{"id":2,"title":"Dune","author":"Frank Herbert","year":1965}],"page":1,"limit":2,"total":3,"totalPages":2}Read one book:
curl http://localhost:3000/api/v1/books/2HTTP/1.1 200 OK
{"data":{"id":2,"title":"Dune","author":"Frank Herbert","year":1965}}Ask for a book that does not exist:
curl http://localhost:3000/api/v1/books/99HTTP/1.1 404 Not Found
{"error":{"code":"book_not_found","message":"No book with that id exists."}}Create a book. Note the 201 and the Location header telling the client where the new book lives:
curl -X POST http://localhost:3000/api/v1/books -H "Content-Type: application/json" -d '{"title":"Foundation","author":"Isaac Asimov","year":1951}'HTTP/1.1 201 Created
Location: /api/v1/books/4
{"data":{"id":4,"title":"Foundation","author":"Isaac Asimov","year":1951}}Create a book with a field missing:
curl -X POST http://localhost:3000/api/v1/books -H "Content-Type: application/json" -d '{"title":"No Author"}'HTTP/1.1 400 Bad Request
{"error":{"code":"missing_fields","message":"Both title and author are required."}}Replace the whole book, then change just its year:
curl -X PUT http://localhost:3000/api/v1/books/4 -H "Content-Type: application/json" -d '{"title":"Foundation","author":"Isaac Asimov","year":1951}'
curl -X PATCH http://localhost:3000/api/v1/books/4 -H "Content-Type: application/json" -d '{"year":1952}'Both answer 200 OK. The PATCH reply shows the year changed to 1952 and nothing else moved:
{"data":{"id":4,"title":"Foundation","author":"Isaac Asimov","year":1952}}Delete it, and the server answers with nothing at all, which is the point of 204:
curl -X DELETE http://localhost:3000/api/v1/books/4HTTP/1.1 204 No ContentFinally, ask for a route that does not exist. Express would normally answer with an HTML page; the last handler in the file catches it and returns JSON instead, so a client never has to parse HTML to learn it asked for the wrong thing:
curl http://localhost:3000/api/v1/magazinesHTTP/1.1 404 Not Found
{"error":{"code":"route_not_found","message":"That endpoint does not exist under /api/v1."}}The wrong turn: 200 OK with an error inside
This is the mistake that costs beginners a whole afternoon, because everything looks fine until the frontend does the wrong thing. Here is the version of the single-book route that gets it wrong:
app.get("/api/v1/books/:id", (req, res) => {
const book = books.find((b) => b.id === Number(req.params.id));
if (!book) return res.json({ error: "Book not found" }); // status is 200 here
res.json({ data: book });
});We ran it. Asking for book 99 answers:
HTTP/1.1 200 OK
{"error":"Book not found"}The body says the book is missing and the status says everything worked. A frontend that checks response.ok shows an empty book page, or crashes reading data.title from a body that has no data. The fix is one call: res.status(404).json(...), as in the worked example. The rule is blunt and worth memorising: the status code is the answer, and the body is the detail. Never let them disagree.
Try it yourself
Add a GET /api/v1/authors endpoint to the same server, using the authors from item 57: Tolkien, Herbert and Gibson. Give it the same pagination as the books list, and return 404 with the book_not_found style error shape, using the code author_not_found, when an author id does not exist. Then test it three ways with curl: page 1 with limit 2, one author by id, and an id that does not exist. Check that the missing author answers 404, not 200.
Continue in the free course: Node & Express API Foundations →
Common mistakes
- Verbs in URLs.
POST /createBooksays the action twice. The method already says it. UsePOST /books. - 200 for everything. A created book is 201, a missing book is 404, a bad request is 400. A client that only reads status codes should still get the right answer.
- PUT when you meant PATCH. Sending half a book with PUT wipes the fields you left out. Send the whole thing, or use PATCH.
- No pagination on list endpoints. It works with three books and falls over with three thousand. Page from the start.
- Errors in different shapes. One endpoint returns
{error: "not found"}, another returns{message: "missing"}, and the frontend needs a handler per endpoint. One shape, everywhere, as in section 6.
Frequently asked questions
Should the version be v1 or 1.0?
Use v1. The short form is the convention in REST APIs, and /api/v1/books is what clients expect to see.
What if I only have one client, my own frontend?
Design it properly anyway. The second client arrives sooner than you think: a mobile app, a teammate's script, or your own admin page. A clean API costs nothing extra now and saves a rewrite later.
PUT or PATCH for a profile edit form?
PATCH. A form sends the fields the user changed, and the rest should stay as they are. PUT would need the form to send every field, including the ones the user never touched.
Should errors include a stack trace?
No. A stack trace tells an attacker how your server is built and tells a client nothing useful. Log it on the server, and send the client a code and a plain message.
When do I need version 2?
When you want to change the shape of a response: rename a field, remove one, or change what a field means. Adding a new field or a new endpoint does not need a new version, because old clients ignore fields they do not know.
Follow the Full-Stack Developer Roadmap
Build complete web applications, frontend, backend APIs, databases and deployment. Free, step by step, at your pace.
View the Roadmap