Lesson 40 · Web and backend

REST APIs

An API lets one program ask another for things. A REST API gives every thing (a resource) its own URL and uses HTTP methods on it: GET reads, POST creates, PUT replaces, PATCH changes a part and DELETE removes. Follow a small to-do API call by call, read the status codes and JSON bodies it sends back, and see why every request stands alone and which requests are safe to send twice.

12 min12 steps5 questionsIntermediate

Fig 40 · Interactive

Loading figure…

or ← →

Check yourself

5 quick questions

Pick an answer to see why. Your score saves with your progress.

01Which request should a to-do app send to read the to-do with id 3, without changing anything?

GET reads a resource and is safe: it never changes anything on the server. /todos/3 is the URL of that one to-do.

02The client sends POST /todos with {"title": "jam"} and it works. What does the server answer?

201 Created means a new resource was made. The Location header tells the client its URL, here /todos/3.

03What is the difference between PUT and PATCH?

PUT replaces the resource with what you send. PATCH, here as a JSON Merge Patch like {"done": true}, changes only the fields you send.

04A server answers 404 Not Found. What does that tell you?

Codes in the 400s mean a problem with the request: 404 means nothing is at that URL. Broken JSON gets 400 Bad Request; a server failure gets a 500 code.

05A reply got lost, so the app resends its request. Which request makes a duplicate if it ran twice?

GET, PUT and DELETE are idempotent: twice has the same effect as once. POST is not: each POST makes another new to-do.

Key terms

Glossary

API: Application programming interface: the requests a program accepts from other programs, and the answers it gives.
REST: A style for web APIs: every resource has a URL, HTTP methods act on it, and each request stands alone.
Resource: A thing the server keeps that has its own URL, such as one to-do (/todos/3) or the list of them (/todos).
HTTP method: The verb of a request: GET reads, POST creates, PUT replaces, PATCH changes a part, DELETE removes.
Status code: The three-digit number on the first line of a response, after HTTP/1.1: 2xx worked, 4xx the request was wrong, 5xx the server failed.
JSON: A plain-text format for data: objects in { }, lists in [ ], text in double quotes, plus numbers, true, false and null.
Stateless: The server keeps no memory of the client between requests, so each request carries everything it needs.
Idempotent: Sending a request twice has the same effect on the server as sending it once. GET, PUT and DELETE are; POST is not.

Fine print

Notes and sources

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.
As a method, PATCH is not promised to be idempotent (RFC 5789). This body is a JSON Merge Patch (RFC 7396, sent as application/merge-patch+json): the fields you send replace those fields and the rest stay.
Sending the same DELETE again gets 404 Not Found, yet the table ends up the same. Idempotent is about the effect on the server, not the reply.
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.
api.example.com is a name reserved for examples (RFC 2606). requests is a popular third-party Python library (pip install requests); Python's own urllib.request can do the same with more code.

Quiz Unlocks after the last step.