# REST: Resources, Endpoints and Methods

A REST API names each kind of thing it holds with a plural noun, such as /plots for every plot and /plots/7 for one, lets the HTTP method be the verb, answers each action with the status code that fits it, and never changes anything on a GET.

Apprentice · REST API · Web Development · Python · Updated November 19, 2026

By Gregor Dzierzon

## After this lesson you can

- Design a resource's endpoints with a plural noun in the path and the HTTP method as the verb
- Choose the method, path and success status for listing, getting, adding, changing and removing an item, and keep every GET read-only

## Key takeaways

- A resource is a kind of thing an API holds, such as the garden's plots. Its path is a plural noun, /plots for all of them and /plots/7 for one.
- The method is the verb. GET reads, POST adds, PUT replaces, PATCH changes some fields and DELETE removes, so one path can have several endpoints.
- Adding answers 201 Created with the new item, removing answers 204 No Content with no body, and the rest answer 200 OK, or 404 when the item isn't there.
- Filters go in the query string, such as /plots?free=true, so they can be combined, instead of getting paths of their own.
- A GET only reads. Browsers and chat apps follow GET links by themselves, so a GET that changes data will change it by accident.

The addresses of an API are a promise. A phone app, a web page and another team's code will all call them, and once they do, renaming one breaks every caller. Before you write a route, you choose its method and its path, and a few naming rules settle that choice and make your API one people can guess. Most public APIs you'll call, from online stores to maps to payments, follow these rules, called REST.

The example is Greenleaf Community Garden again, whose app needs to list its plots, look one up, and add, change or remove plots as neighbors come and go.

## Addresses named after actions

The garden's first plan for its API named every address after what it does:

```text
GET  /getAllPlots
GET  /getPlot?number=7
POST /createPlot
POST /updatePlotGardener
POST /removePlot?number=7
```

It would work, but it has three problems. Every new action needs a new name, and nobody can guess it: is it `/removePlot` or `/deletePlot`, `/getPlot` or `/plot`? A developer writing the app has to look up each one. And every change is a POST, so the method says nothing; it's the name that does the work, and the names are made up as the API grows.

## Resources are nouns, methods are verbs

Think of a library. The shelves are labeled with what's on them, *Cookbooks* or *Gardening*, and what you want to do with a book (borrow it, return it, renew it) you say at the desk. The label never changes with the job.

**REST** (read "rest", short for REpresentational State Transfer) is a style of designing APIs the same way. The paths name things, and the HTTP methods are the verbs from *HTTP in Plain Words: Requests and Responses*. Each kind of thing an API holds is a **resource**: the garden's plots, its gardeners, its waiting list. A resource's path is a plural noun: `/plots` means all the plots, and `/plots/7` means plot 7, read "plots slash seven".

An **endpoint** is a method and a path together, such as `GET /plots/7`. Here is every endpoint of the plots resource, with the status code each one answers when it works:

| Action | Endpoint | When it works |
|---|---|---|
| List every plot | `GET /plots` | 200 OK, with the list |
| Get one plot | `GET /plots/7` | 200 OK, with plot 7 |
| Add a plot | `POST /plots` | 201 Created, with the new plot and its number |
| Replace a plot's whole record | `PUT /plots/7` | 200 OK, with the new record |
| Change some of a plot's details | `PATCH /plots/7` | 200 OK, with the changed plot |
| Remove a plot | `DELETE /plots/7` | 204 No Content, with no body |

Two paths cover six actions, and `/plots/7` alone has four endpoints: the method tells the API which one you mean. POST goes to the list's own path, because the new plot has no number until the API gives it one. When plot 7 isn't there, the four endpoints that name it answer 404: there's nothing at that address. These actions are often called **CRUD**, read "crud": create, read, update and delete.

PUT and PATCH both change a plot. PUT sends the whole record, and anything left out is gone. PATCH sends only what changed, such as `{"growing": "beans"}` when Lena switches crops, which is why most apps use PATCH for small changes.

## Naming rules that keep paths guessable

A few more rules keep every path guessable:

- **Plural, always.** `/plots` and `/plots/7`, never `/plot/7`. Mixing the two makes every caller stop and check.
- **Lowercase, with hyphens between words:** `/waiting-list`, not `/WaitingList`.
- **Filters go in the query string,** not in paths of their own: `/plots?free=true` instead of `/freePlots`. Then two filters combine, `/plots?free=true&size=large`, with no new path.
- **Things that belong to one item go under it,** one level deep: `/plots/7/harvests` is plot 7's harvests.

## A GET never changes anything

Suppose the garden adds a shortcut for freeing a plot, `GET /plots/7/release`, so a volunteer can tap a link. Then someone pastes that link into the gardeners' group chat. The chat app fetches every link to build a preview, and that fetch is a GET: Lena has lost plot 7, and nobody clicked anything.

Browsers that load pages ahead of time, link previews and search engines all send GET requests by themselves, because GET is a **safe method**: one that only reads. A GET in your API must never add, change or remove anything. Changes go through POST, PUT, PATCH and DELETE, which nothing sends without being asked. Freeing plot 7 is `PATCH /plots/7` with `{"gardener": null}`.

## Do it: find the endpoint for each plot action

The garden's app has five plot actions, and each one needs its endpoint: the method and the path, following the table in this lesson.

- `action`: one of `"list"`, `"get one"`, `"add"`, `"change"` (change some of a plot's details) or `"remove"`.
- `number`: the plot's number, such as `7`, for `"get one"`, `"change"` and `"remove"`. For `"list"` and `"add"` it's `None`.

**Your job:** write the function `endpoint_for(action, number)` so it returns two strings together, in round brackets: the method in capital letters, then the path, such as `("GET", "/plots")`. Values written together like that are a **tuple**.

- `"list"` and `"add"` use the plots' own path, `/plots`.
- `"get one"`, `"change"` and `"remove"` use the path of one plot, such as `/plots/7`.

Worked through: `endpoint_for("change", 7)` is about plot 7, so its path is `/plots/7`. Changing some of a plot's details is PATCH. It returns `("PATCH", "/plots/7")`.

Practiced live on the lesson page: write the Python right there and check it.

## Check yourself

2 questions to try on the lesson page.

## So what

With plural nouns for paths and methods for verbs, anyone who knows one REST API can guess most of yours, and a GET that only reads keeps a link preview from changing your data.

## Key terms

- [REST](https://www.ask-codey.com/glossary/rest)
- [Resource](https://www.ask-codey.com/glossary/resource-rest-api)
- [Endpoint](https://www.ask-codey.com/glossary/endpoint-rest-api)
- [Resource Naming](https://www.ask-codey.com/glossary/resource-naming)
- [Safe Method](https://www.ask-codey.com/glossary/safe-method)
- [CRUD](https://www.ask-codey.com/glossary/crud)

## Related

- [HTTP in Plain Words: Requests and Responses](https://www.ask-codey.com/lessons/fastapi-http-requests-and-responses)
- [Status Codes and Headers](https://www.ask-codey.com/lessons/fastapi-http-status-codes-and-headers)
- [Routing by Hand, and Why Frameworks Exist](https://www.ask-codey.com/lessons/fastapi-http-routing-by-hand)

Source: https://www.ask-codey.com/lessons/fastapi-rest-resources-and-endpoints
