A browser asks a server for a page, and a person reads the answer. But most of the requests on the internet are never read by a person. One program asks another program for data, and the answer goes straight into code. That conversation is an API, an Application Programming Interface. This lesson reads the menu, places an order, and shows why keys and limits exist.
Difficulty: Beginner · Know this first: F23 — HTTP: How Clients and Servers Talk
Every hop charges a little time. The bar below is a worked example for this lesson's scenarios, not a measurement from a live system. The shape is honest: the program's work is the biggest slice, and a refused request is cheap because no work happens. Step through the lesson or switch the scenario and watch the bar change.
Extra diagram · from scratch to master
Start with one program. Add one endpoint at a time until the whole menu is on the wall, locked door included.
Extra diagram · from scratch to master
Start with one caller. Add one protection at a time until you can see why a service with no keys and no limits cannot survive.
Call the weather API. Pick an endpoint, choose whether to send a key, and make some calls. The simulator counts them against a limit of 100 per hour, a teaching example, and shows the status that comes back. The numbers are exact for the table in this simulator.
Two reads and one write. The reads are safe to repeat. The write creates something every time it runs.
The key travels in a header. A missing key and a wrong key fail differently, and the code tells you which one it is.
The limit is 100 calls per hour for this key, a teaching example. The slider sets how many this key has already made.
Try this: (1) Weather, valid key, 10 calls. Status 200 OK, 90 calls left, the weather comes back. (2) Same, no key. Status 401 Unauthorized, and the calls count does not matter. (3) Weather, valid key, 100 calls. Status 429 Too Many Requests, 0 left, try again next hour. (4) Order, valid key, 10 calls. Status 201 Created, an order exists now.
Three questions. No score is saved anywhere — this is just you against the material.
I take the same idea four times here. First I learn what it is and why it exists. Then I learn to use it and read what it tells me. Then I design with it so one failure cannot take the system down. Last I run it for the world.
Definition: An API is a menu of things one program offers to other programs. Each item is an endpoint, an address where a program can ask for one thing. The request is HTTP, and the answer is usually JSON, data shaped for code to read. A key names the caller. A limit budgets the caller.
Types:
Uses: I use this whenever an app needs data from another program. I read the menu first, then I ask for exactly what is on it.
Dimensions: At low traffic one key and one endpoint is enough. What breaks first is a missing key, and I notice it as a 401. It costs nothing to learn the menu habit. It costs hours to guess at an API without one. The trade is simple: a menu limits what you can ask for, and that limit is what makes the answers reliable.
Definition: A key travels in a header and says who is asking. The gateway checks the key, counts the calls, and enforces the limit. 401 means unknown caller. 403 means known caller, not allowed. 429 means too many calls. A 200 with a missing field is worse than a 500, because the caller trusts the 200.
Types:
Uses: I use curl at this level. I call an endpoint with a key, read the status and the remaining quota, and tell a key problem apart from a limit problem in one command.
Dimensions: As an API grows, the number of callers grows with it, and each one needs its own key and its own limit. What breaks is a leaked key, and I notice it in a usage spike on one key while the rest are flat. It costs key rotation and the habit of never putting a secret in a path or a log. The trade is that every protection costs a few milliseconds, and it buys the service its life.
Definition: At this level I design the menu: consistent paths, consistent shapes, versioned endpoints so a change does not break every caller at once. Errors carry messages a human can act on. Idempotency keys make a repeated POST safe. The gateway enforces the rules so the program behind it never has to.
Types:
Uses: I use this when I build or review an API. I read the menu like a stranger and ask whether I could order from it without asking anyone for help.
Dimensions: At ten times the callers the gateway is the wall, and its counters are the state that matters. What breaks is a limit set once and forgotten, and I notice it when a good caller gets 429s on a busy day. It costs limits set per caller, not one number for the world. The trade is that a strict limit protects the service and a generous one protects the caller, and the number is a business decision.
Ask for JSON, read JSON. An API answers in JSON, and JSON is meant to be read by a program, not by eye. I pipe the answer through python3 -m json.tool, which prints it indented and readable. If the tool fails, the answer was not JSON, and that is the first clue that something went wrong.
$ curl -s -m 8 https://httpbin.org/json | python3 -m json.tool | head -8
{
"slideshow": {
"author": "Yours Truly",
"date": "date of publication",
"slides": [
{
"title": "Wake up to WonderWidgets!",
"type": "all"
Every flag in the commands above, letter by letter.
curl -s: -s means silent. curl -m 8: -m 8 gives up after 8 seconds. It is the short form of --max-time 8.python3 -m json.tool: -m runs a module by name. json.tool reads JSON and prints it indented. Without it, the JSON arrives on one line, and I cannot read it.head -8 keeps the first 8 lines. The response is longer, so the rest is cut.curl -H "Accept: application/json" sends a header with the request. APIs read it to decide what format to answer in. Without the header, some APIs answer with HTML or an error.Check it: run the command above, then run curl -s -m 8 -H "Accept: application/json" https://httpbin.org/json | head -3. The header changes nothing here, because this API always answers JSON. On a strict API, it is the difference between an answer and an error.
Try it: run the command above. The output is indented JSON, and you can read the slideshow title in it. Now run the same curl without the pipe. The output is one long line. Same data, unreadable. The pipe is the difference between data and information.
The header is part of the answer. An API answer has headers as well as a body, and the headers carry facts the body does not: the content type, the rate limit, and the request id. I read the headers with curl -D - before I trust the body.
$ curl -s -D - -o /dev/null -m 8 https://httpbin.org/get | grep -i -E "^HTTP|content-type"
HTTP/1.1 200 Connection Established
HTTP/1.1 200 OK
content-type: application/json
Every flag in the commands above, letter by letter.
curl -D -: -D dumps the response headers. The - means standard output, not a file. Without the dash, -D needs a filename.grep -i ignores case, so ratelimit matches RateLimit. grep -E turns on extended regex, so | means or. Together they keep the status lines and the content-type lines.curl -D headers.txt writes the headers to a file instead of the screen. Same flag, different target. I use the file form when I want to read the headers after the request finishes.Check it: run the command above, then run curl -s -D hdrs.txt -o /dev/null -m 8 https://httpbin.org/get and head -2 hdrs.txt. The headers land in the file.
Try it: run the command above. The content type says application/json, so the body is JSON. If it said text/html, the API probably sent an error page, and parsing it as JSON would fail. Check the type before you parse.
Definition: At this level an API is a product: documented, versioned, monitored per endpoint, with quotas per customer and a deprecation path that gives callers time to move. I know which endpoints are hot, which callers are heavy, and which version can be retired. The gateway is a platform, not a door, and the API's reliability is measured from the caller's side.
Types:
Uses: I use this when an API serves strangers: I monitor what callers see, I announce changes before I make them, and I retire versions on a schedule, not by surprise.
Dimensions: At a hundred times the callers the API is a business, and a breaking change is an incident with customers, not a bug with a fix. What breaks is a change nobody announced, and I notice it in caller errors, not in my own dashboards. It costs a changelog, a sunset policy, and the discipline to keep old versions running until their date. The trade is that stability costs velocity, and the callers pay for the stability with their trust.
Rate limits are in the headers. An API that many people use limits how often you may call it. The limit and the remaining count travel in the headers. I read them before I write a loop that calls the API a thousand times, because the loop will be stopped halfway, and the error will not say why.
$ curl -s -I -m 8 https://api.github.com/zen | grep -i -E "ratelimit|HTTP/"
HTTP/1.1 200 Connection Established
HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 9
X-RateLimit-Used: 51
X-RateLimit-Resource: core
Every flag in the commands above, letter by letter.
curl -I: -I sends a HEAD request. Headers only, no body. The rate limit headers are in the answer, which is why this command is the way to read them without downloading anything.curl -m 8 gives up after 8 seconds. grep -i -E matches case-insensitively with extended regex, so ratelimit matches RateLimit and HTTP/ matches the status line.Check it: run the command above. The output shows X-RateLimit-Limit: 60. That is 60 requests per hour for this API without a key.
Try it: run the command above. The limit is 60 calls per hour, and in the run above 9 remain. A script that calls the API 20 more times will be refused. Read the remaining count first, and stop before it hits zero. The API will not warn you. The header already did.
REST is the style most APIs in this course follow, and its rules are simple: resources have names, methods have meanings, and the server keeps no memory of the caller between requests. Each request carries everything the server needs. That is why a key travels on every call, not just the first one.
Idempotency is the word for a request that is safe to repeat. A GET is idempotent: asking twice changes nothing. A POST usually is not: sending it twice creates two orders. An idempotency key is a string the caller sends with a POST, so the server can recognize a retry and return the first answer instead of creating a second order.
Versioning is how an API changes without breaking its callers. /v1 keeps working while /v2 offers the new shape. The old version gets a sunset date, announced in advance. A breaking change without a version is not a change. It is an outage for every caller at once.
A gateway does more than check keys. It logs every call, it caps the rate, it routes by path, and it can hide the programs behind it so callers never learn their addresses. The full machinery is L18, API Gateways, later in this course. This lesson was the idea. That lesson is the machine.
At 10x the traffic, the shape holds and the numbers grow. The gateway counts more calls, the program does more work, and the limit is the budget that keeps both alive.
At 100x, the design changes. The API is a product with customers, quotas, and a changelog. The gateway is a platform, and the reliability is measured from the caller's side, not from the server's logs.
Try it: fetch JSON and read it. Run the httpbin command from the Advanced section and read the slideshow title in the output. Then run it without the json.tool pipe and compare. The data is the same. The readable version is the one you can debug with.
$ curl -s -m 8 https://httpbin.org/json | python3 -m json.tool | head -8
{
"slideshow": {
"author": "Yours Truly",
"date": "date of publication",
"slides": [
{
"title": "Wake up to WonderWidgets!",
"type": "all"
A partner's app started failing on a Monday morning. Every call it made came back 401 Unauthorized. Our service was up. Every other partner worked fine. The failing partner swore nothing had changed on their side, and they were right. Something had changed on ours, three days earlier, and nobody had told them.
Three things. First, key cleanup now requires a check: has this key been used in the last 30 days, and does anyone own it? A key in use is not an old key. Second, every key has an owner and a contact, written down, so a revocation can be announced before it happens. Third, the 401 response now carries a message that says the key is revoked, not just that it is unknown, so the next person to see it knows exactly what happened. The lesson was not about keys. It was about changes with customers attached: a cleanup is a change, and a change to a key is a change to a customer.
Design an API for a small library. Programs can list books, see one book, borrow a book, and return a book. Other programs will call it, and one of them is written by a partner you have never met.
Start with the count. Four endpoints, each with one method and one success code. A limit of 100 calls per hour per key is generous for a library and small enough to protect the service. The list endpoint is paged at 20 books per page, because a library with 10,000 books must never send all of them in one answer. The borrow endpoint takes an idempotency key, so a retry returns the first answer instead of a second loan.
A key per caller buys accountability and costs onboarding: every new caller needs a key issued and a contact recorded. A limit buys protection and costs a good caller getting 429s on a busy day, so the limit is set per caller, not one number for the world. Versioning buys safe change and costs running two versions side by side until the sunset date. And the error messages are written for the stranger: a partner you never met must be able to fix a 401 from the response alone.