Designing your first REST API: five rules we repeat every week
Good APIs are boring in the best way. These five rules keep our trainees' backends predictable, easy to use and easy to change later.

A REST API is a promise to everyone who uses it: the frontend team, the mobile app, and whoever joins the project next year. Break the promise and every app built on top of it breaks too. That is why, in the Backend path, we spend almost as much time on API design as on writing the code behind it.
Over many intakes, our review comments boiled down to the same five rules. We now repeat them every week, and trainees start catching each other's mistakes long before the trainer does.1. Name resources with nouns, not verbs
The URL says what the thing is; the HTTP method says what you are doing to it. Verbs in URLs are a sign that the design is leaking implementation details.
GET /courses list coursesGET /courses/42 one coursePOST /courses create a coursePATCH /courses/42 update part of itDELETE /courses/42 remove it2. Use status codes honestly
A 200 with an error message inside is a lie that every client has to work around. Return 201 when something is created, 400 when the input is wrong, 404 when it does not exist and 409 when it conflicts with something that does.
3. Validate every input at the edge
Never trust what arrives. Validate the shape and the values as soon as a request enters the API, and return a clear message about what was wrong. Everything after that can assume clean data.
app.post("/courses", (req, res) => { const { title, weeks } = req.body; if (!title || weeks < 1) { return res.status(400).json({ error: "title and weeks are required" }); } // safe to continue});4. Return the same shape every time
If a course has a `title` in one response, it should never be `name` in another. Pick a shape, document it and keep it. Lists should always be lists, even when they are empty, and errors should always look the same.
Clever APIs are hard to use. Predictable ones are a pleasure.
5. Version before you need to
The day will come when you must change a response in a way that breaks old clients. If your routes already start with a version, that day is a calm one: add the new version next to the old and give everyone time to move.
Start with /v1 even on your first project.
Never change the meaning of a field inside a version.
Announce removals early and keep the old version running for a while.
Putting it together
None of these rules is clever, and that is exactly the point. In the final project of the Backend path, trainees build an API for the Frontend path's product site. When the frontend team can use it without asking a single question, the design has done its job.





