How APIs work
Why this matters
Every call to an LLM is an HTTP request. So is every integration you've used in marketing: pulling numbers from an ad platform, adding a contact to a CRM, sending an email through a delivery service. When an AI agent "uses a tool", it's usually making one of these requests. Learn to read requests and responses, and most API errors explain themselves.
- Name the parts of a URL and what each one does
- Choose the right HTTP method for reading, creating, updating and deleting
- Read a status code and know whose problem it is
- Turn a JSON response body into Python data
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:
- a method: what you want to do (read, create, change, delete)
- a URL: what you want to do it to
- headers: extra information about the request, such as who you are and what format you're sending
- an optional body: data you're sending, such as a new campaign's details
Every response has three:
- a status code: a number saying how it went
- headers: information about the response
- a body: the data itself, often JSON
Anatomy of a URL
https://api.gradient.test/v1/campaigns?status=active&channel=search
| Part | Here | What it does |
|---|---|---|
| Scheme | https:// | how to connect; the s means encrypted |
| Host | api.gradient.test | which server to talk to |
| Path | /v1/campaigns | which resource on that server; v1 is the API version |
| Query string | ?status=active&channel=search | options for this request, as key=value pairs joined by & |
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
| Method | Meaning | Example |
|---|---|---|
GET | read something | list campaigns |
POST | create something, or submit data to be processed | create a campaign; send a prompt to an LLM |
PUT / PATCH | replace / partly update something | change a campaign's budget |
DELETE | remove something | delete a draft |
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.