Web APIs in depth — HTTP, REST and status codes

When a frontend, a mobile app, or an external system fetches or saves data with your backend, it happens over an API. On the web, the vast majority of APIs are built on HTTP—the same protocol the browser uses to fetch pages. If you understand HTTP properly, you understand the foundation under virtually all web communication, not just APIs.

§HTTP — request and response

HTTP is built around a client sending a request and the server sending a response. A request has a method (what do I want to do), a path (what do I want to do it with), possibly headers (metadata), and maybe a body with data. The response has a status code (did it go well), headers, and typically a body with the result — on a web API often in JSON format. Each request stands alone by default; the server remembers nothing between them, unless you consciously build it with, for example, a session or a token.

§The methods tell the intent

HTTP methods (also called verbs) tell you what you want. Using them according to their meaning makes an API predictable. An important property is whether a method is safe (does not change data) and idempotent (the same call repeated gives the same state) — this determines whether it is safe to repeat a call that may not have reached.

§REST — resources instead of actions

REST is a widespread style for web APIs. The core idea is to think in resources — things that have an address — rather than in actions. Instead of an endpoint like 'createUser' you have a resource 'users', which you use methods on: get the list, create a new one, get a specific one, update it, delete it. Addresses are named after the things (nouns, preferably plural), and the method determines the action. This gives an API that is easy to guess and consistent to use.

§Stave the cross over the head

Status codes – the answer in one number

• 012-series: it worked — e.g. created or retrieved
• 023-series: client should go elsewhere
• 034-series: the client did something wrong — e.g. invalid input, not logged in, no access, not found
• 045-series: the server failed — it is not the client's fault

§Versioning and contract

When others build on top of your API it is a contract: if you change it suddenly you break their systems. That's why you version APIs so a new version can come while the old one still works for those not ready to switch. Document the contract – which addresses exist which fields are expected what is answered – so others can use your API without reading your source code or guessing.

§Safety belongs

An API is a door into your data often without a user interface to hide anything. So web security applies in full force: require login and check access on every call validate all input on the server use encryption in transit and consider limiting how many calls a client can send so the API cannot be overloaded. An open undocumented and unmonitored API is an obvious target.

“A good API can be used without reading the code behind — the method, address and status code tell nearly everything by themselves.”

— Common teaching principle in API design