APIs and REST: how programs talk to each other

An API is a set of rules for how programs exchange data. REST is an HTTP API style: the address names a resource, the method the action, the code the result.

Programs talk too

So far the “client” of a server has been a browser, and a person read the answer. But more and more on the web, programs talk to each other. Your page asks a server for the list of offerings (you did that in the lesson on fetch). A mobile app sends an inquiry. A shop’s site asks a courier service for a price. An AI model reads data through a tool. Such conversations need rules: what to ask, in what form, and which answers are possible. A set of such rules is called an API (Application Programming Interface).

Most often a web API is plain HTTP, which you already know: a request with a method and an address, a response with a status code and a body, and usually the body is JSON. The only difference from a page is that the response is meant for a program, not for eyes.

REST: resources and verbs

The most common style of such APIs is called REST (Representational State Transfer). Roy Fielding, one of the authors of HTTP, described it in his doctoral dissertation in 2000. The idea is to use HTTP the way it was designed:

• the address names a resource, a noun in the plural: /items (offerings), /items/7 (offering number seven), /requests (inquiries);
• the action is expressed by the HTTP method, not by a word in the address;
• the status code reports the result;
• the server keeps nothing about the client between requests: everything needed arrives in the request itself.

To be honest, what the industry calls a “REST API” usually follows this idea only roughly (strict REST also wants links inside responses, and almost nobody does that). What matters to us are the rules themselves, because they make an API predictable: a developer who sees /items can guess what /requests looks like.

Methods

Each method has an agreed meaning, written down in the HTTP standard (RFC 9110):

• GET: read. It is safe: it changes nothing, so anybody can call it any number of times (a browser, a search robot, an extension).
• POST: create a new resource or perform an action (“send an inquiry”). A repeat may create a second copy, so POST is not idempotent.
• PUT: replace a resource entirely.
• PATCH: change some of its fields.
• DELETE: remove it.

Idempotent means “repeating it does not change the result”: two identical DELETE /items/7 requests leave the server in the same state as one. GET, PUT and DELETE are idempotent, so a client can safely repeat a request if no answer came. POST gives no such guarantee, which is why we disabled the button while sending in the lesson on fetch.

Status codes

You know the groups of codes (2xx, 3xx, 4xx, 5xx). APIs use a fairly definite set:

• 200 OK: success; 201 Created: created (with a Location header holding the address of the new resource); 202 Accepted: accepted, processed later; 204 No Content: success with no body;
• 400 Bad Request: the request is wrong (a field is missing); 401 Unauthorized: sign in first; 403 Forbidden: signing in isn’t enough, this isn’t allowed; 404 Not Found: there is no such resource; 409 Conflict: it conflicts with the current state; 422: the data is understood but failed validation; 429 Too Many Requests: too often;
• 500 Internal Server Error: a fault on the server, and the client is not to blame.

Pick a request and look at the response. Two of the requests break the rules on purpose:

GET /items HTTP/1.1
Host: api.riverbend.example

200 OK
[{ "id": 1, "title": "First offering" }, …]

/items:
  get:
    responses:
      '200': { description: An array of offerings }

A good error

The most annoying thing in somebody else’s API is a 500 with no explanation, or a 200 with the word “error” inside. Agree on how errors look and keep to it everywhere. The minimum is the right status code, a short machine-readable code (invalid, not_found) by which a program decides what to do, and text a person can read. There is a standard for this format, RFC 9457 “Problem Details”. Details (the stack trace, passwords, paths on disk) don’t go in the response. They stay in the server’s log.

Versions, pages and safety

• Versions. An API changes, and the people who use it can’t keep up with you. So the version number goes in the address (/api/v1/items), and the old version lives as long as someone uses it.
• Pages and filters. A list of a thousand records isn’t returned whole: /items?page=2&limit=20, /items?q=surveying.
• HTTPS always, and especially when the request carries personal data (a name, a phone number). Data protection law expects you to protect it (in the UK and the EU that is the GDPR and its UK version, which the lesson on authentication returns to), and encryption in transit is the first step.
• Validate input. Anything can arrive in a request: the server checks every field and doesn’t trust the client.
• Rate limiting, so that one attacker can’t flood the server.

OpenAPI: the contract as a file

So as not to explain an API in words, it is described by a file in the OpenAPI standard: YAML or JSON that lists the addresses, methods, parameters, and the shapes of requests and responses. The format grew out of the Swagger project (2011) and has been developed as an open standard since 2015. From such a file you automatically get interactive documentation (Swagger UI), stubs for client programs, and a check that the server answers as promised.

paths:
  /requests:
    post:
      summary: Create an inquiry from the form
      responses:
        '201':
          description: Inquiry created

Indentation with spaces matters: in YAML, nesting is set by it.

How to try an API

Three ways, and none needs special software. The Network tab in the developer tools shows the page’s real requests. The curl command in a terminal (curl https://riverbend.example/api/v1/items shows the response). And the Swagger editor (editor.swagger.io), where you can paste an OpenAPI file and press “Try it out”.

Practice

You are on a site from the 2022 era, when sites talk through APIs (the time of Jamstack). Describe your project’s API in an OpenAPI file: the list of your offerings, one offering, and creating an inquiry from the form. You write the text in a pre block right on the page, and the checks read it.

Three rules the checks will catch: paths are plural nouns with no verbs; GET reads, while an inquiry is created with POST and answers 201; the 200, 400 and 404 answers and a shared error format are described. And one rule the checks won’t understand but data protection law will: personal data from the form is accepted only over HTTPS. Write that in the description of the inquiry.

What was wrong before

Before REST there was a fashion for SOAP: messages in XML envelopes, with huge descriptions (WSDL) and tools without which they couldn’t be read. And in the simple APIs of the 2000s everything went through one address with an action parameter (/api.php?action=deleteItem&id=7). The method was almost always GET or POST, picked at random, and the 200 came back both on success and on failure, only with different text. Any program that read such an API first had to write a parser for “what did they mean here”.

Today’s convention is humbler but more reliable: the address names a thing, the method says the action, the status code says whether it worked, and an OpenAPI file writes all of it down for people and machines.