APIs and resources
An API (application programming interface) is a set of rules one program uses to ask another for things. Here a to-do app, the client, asks an API server. A REST API sends those requests over HTTP, the web's protocol.
REST treats each thing the server keeps as a resource with its own URL. /todos is the whole list; /todos/1 is the to-do with id 1. The server keeps them in a table, one row per to-do.
Reading and writing
The client sends GET /todos. GET only reads; it never changes anything. The server reads every row and answers 200 OK, meaning it worked, with the list in the body, the data part of the message.
The body is JSON, plain text for data. { } holds an object of named values, [ ] holds a list, and text sits in double quotes. Any language can read it; Python turns it into dicts and lists.
To add a to-do the client sends POST /todos with a JSON body. The server picks the next id, 3, saves a new row and answers 201 Created. A header (a named line before the body) called Location gives the new URL.
PUT /todos/3 sends a whole new version of to-do 3. The server swaps the old row for it, title and all, and answers 200 OK with what it saved.
PATCH sends only the fields to change. Here {"done": true} ticks the to-do off, and its title stays tea. Use PUT to replace everything, PATCH to change a little.
DELETE /todos/2 asks the server to remove to-do 2. It deletes the row and answers 204 No Content: it worked, and there is nothing to send back.
Rules of the road
Ask for /todos/2 now and the server answers 404 Not Found. Codes starting with 4 mean the client got something wrong, like 400 Bad Request for broken JSON. Codes starting with 5, like 500, mean the server failed.
REST is stateless: the server keeps no memory of the client between requests. So every request carries all it needs, such as a token in its Authorization header that says who is asking.
Replies can get lost, so clients sometimes resend. PUT and DELETE are idempotent: twice has the same effect as once. The first PUT renames to-do 3 to chai; the second changes nothing. POST is not: two POSTs make two new to-dos, 4 and 5.
Two more habits. A version in the path, /v1/, lets the API change later as /v2/ without breaking old apps. Long lists come in pages: this API sends two per page, so page=2 returns to-dos 4 and 5.
What happens
;; step 1/12 · api
API application programming interface:
the requests a program accepts, and its answers
client the program that asks (our to-do app)
server the program that answers (the API server)
REST a style for web APIs, built on HTTP
The cards leave out headers real messages also carry, such as Host (shown once), Content-Type: application/json and Content-Length. Each JSON body is exactly what Python's json.dumps writes, split across lines. REST is an architectural style described by Roy Fielding in 2000. Many APIs called REST follow only part of it. Ids, the page size and the error bodies here are this example API's own choices: there is no single standard for pagination.