REST and Resource-Oriented Design

Before an API has a single field, it has a list of paths, and the paths are what every client writes into its code first. A good list lets a developer guess the path they need before reading the documentation; a poor one sends them to the documentation for every call, and keeps them there.

The topic begins with REST, the set of constraints most web APIs follow in part, and with what a resource and its identifier are. Then it builds paths: collections and items, a worked bookshop, how far to nest, how to model actions such as cancelling that are not plain updates, and how query parameters filter, sort and search. A gotcha shows the most common mistake, verbs in paths, and the Richardson maturity model gives a scale for how much of HTTP an API uses.

The methods each path is called with come from the first topic of this subject. The fields inside each request and response are the next topic's subject.

By the end you can name the REST constraints and what each buys, tell a URL from a URN, design collection and item paths for a new domain, model an action, express a filter as query parameters, and place an API on the maturity model.