How APIs work

Two messages: a request and a response

HTTP is the set of rules browsers and servers use to talk. It works like ordering at a counter. You (the client) place an order (the request), and the kitchen (the server) hands something back (the response). When you open a web page, your browser is the client, and the response is the page for it to draw.

An API (application programming interface) uses exactly the same rules. But it's built for programs rather than people. Instead of a web page, it replies with data, almost always as JSON. Your code is the client.

Every request has four parts:

1. a method: what you want to do (read, create, change, delete)
2. a URL: what you want to do it to
3. headers: extra information about the request, such as who you are and what format you're sending
4. an optional body: data you're sending, such as a new campaign's details

Every response has three:

1. a status code: a number saying how it went
2. headers: information about the response
3. a body: the data itself, often JSON

Anatomy of a URL

https://api.gradient.test/v1/campaigns?status=active&channel=search

You know query strings already: UTM tags are exactly this. In ?utm_source=newsletter&utm_campaign=spring, the analytics tool reads the key-value pairs after the ?. An API reads them the same way. Here they filter which campaigns to return.

api.gradient.test is the academy's practice API. It pretends to be an ad platform with six campaigns and a small product catalog. You can experiment without breaking anything.

Methods

A GET should never change anything on the server. That's why it's safe to repeat. Calls to an LLM are POST requests, because you send a body containing your messages.

Status codes

The status code is the first thing to read in any response. The first digit tells you the family:

The 4xx/5xx split tells you where to look:

• A 4xx means fix your request: a typo in the URL, a missing field, a bad API key.
• A 5xx means the problem is on their side. Waiting and trying again may work.

Two codes you'll see a lot with LLM APIs: 401, meaning your API key is missing or wrong, and 429, meaning you're sending requests faster than you're allowed to.

401 and 403 sound alike. 401 means "I don't know who you are" (no key, or an invalid one). 403 means "I know who you are, and you're not allowed to do this".

Send some requests and watch the codes:

status = 404
print(status // 100)

Headers and bodies

Headers are Name: value lines that travel with a request or response. A few you'll see constantly:

• Content-Type: application/json says the body is JSON.
• X-Api-Key: ... or Authorization: Bearer ... carries your credentials (covered in the API keys lesson).
• Accept: application/json asks for JSON back.

The body of a request or response is just text. When it's JSON, you already know how to work with it. json.loads turns JSON text into Python dictionaries and lists. json.dumps turns Python data into JSON text to send.

Here is a response body exactly as the practice API sends it, as one string:

import json

body = '{"data": [{"id": "cmp_101", "name": "Spring Sale - Search", "clicks": 5470}, {"id": "cmp_104", "name": "Newsletter Promo - Email", "clicks": 1920}], "count": 2}'

result = json.loads(body)
print(type(result))
print(result["count"])
for campaign in result["data"]:
    print(campaign["name"], campaign["clicks"])

Error responses are JSON too, and a well-designed API puts a readable message inside:

import json

status = 404
body = '{"error": {"type": "not_found", "message": "No campaign with id cmp_999."}}'

if status >= 400:
    details = json.loads(body)
    print("Request failed with", status)
    print(details["error"]["message"])

When a request fails, print the status code and the body. The answer to "why didn't this work?" is usually sitting in that message.

import json

new_campaign = {
    "name": "Summer Launch - Social",
    "budget": 1500,
    "channel": "social",
}

body = json.dumps(new_campaign)
print(body)
print(type(body))