REST API

REST is not about "returning JSON over HTTP." It is a set of conventions that make an API predictable: the address and the method tell you in advance what will happen, and the client and the server can evolve independently of each other. Without those conventions every endpoint becomes a surprise — and integration turns into reading someone else's code instead of reading a contract.

The section collects those conventions layer by layer: how to name resources and build addresses, which method is responsible for what, how to pass parameters and paginated results, what format to return data in and — a separate, important one — errors. Plus versioning and describing the contract with OpenAPI, so that the API can be read without running it.

The examples come in four languages — Java, Go, Node, and Python: the principles themselves do not depend on the language, only the plumbing changes.