In Lesson 13.1 you learned the counter: a client sends a request, a service returns a response. Now open the order slip. An API request is not one long mysterious URL — it is a small envelope with five distinct pieces, each with its own job.

A request is an envelope, not a spell

Beginners stare at a full API example and see a wall of text. Take it apart and it is always the same five pieces:

┌── API request envelope ─────────────────────┐
│ 1. URL + endpoint .... where it goes        │
│ 2. Method ............. what kind of action │
│ 3. Query parameters ... small filters       │
│ 4. Headers ............ metadata + auth     │
│ 5. Body ............... structured data sent│
└─────────────────────────────────────────────┘

Learn to spot each one and documentation becomes readable. Miss one and every error looks like magic.

The five pieces

1. URL and endpoint — where the request goes. The base address names the service; the endpoint path names the job. https://api.weather.example is the building; /v1/forecast is the window. Lesson 13.1's SEC example works the same way: data.sec.gov is the building, /submissions/CIK0000320193.json is the window.

2. Method — what kind of action is requested. Four verbs cover almost everything at this stage:

Intent is the key word. Method names describe intent, but the documentation for each endpoint decides exactly what happens. A POST to one endpoint creates a row; a POST to a model endpoint asks for a completion. Same verb, different job — the docs are the authority.

3. Query parameters — small filters in the URL. Everything after the ? narrows the ask: ?latitude=50.85&longitude=4.35&hourly=temperature_2m. No secrets here — parameters are visible in logs and history, so they carry filters, not passwords.

4. Headers — metadata about the request. Two headers matter most right now: Authorization (who is calling — usually a key or token, covered in Class 14) and Content-Type (what format the body is in — almost always application/json in this course). Headers ride along invisibly; they are not part of the URL or the body.

5. Body — structured data sent with the request. Mostly a GET has no body — the URL says everything. A POST usually carries a JSON body: the thing to create, the message to process, the fields to store. If you know JSON files (Class 3) and model structured output (Part IV), you already know this shape.

Side by side: weather and model

Watch the same envelope carry two different jobs:

A harmless weather read (GET, no body):

GET https://api.weather.example/v1/forecast?latitude=50.85&longitude=4.35&hourly=temperature_2m
Headers: (none needed — public demo endpoint)
Body: (none — everything is in the URL)

Purpose of each part: the URL names the service, GET says "read only," the parameters pick Brussels plus the field wanted, no auth header because the demo is public, no body because there is nothing to create.

A model ask (POST, JSON body):

POST https://openrouter.ai/api/v1/chat/completions
Headers:
  Authorization: Bearer sk-or-... (your key)
  Content-Type: application/json
Body:
{
  "model": "deepseek/deepseek-chat",
  "messages": [
    {"role": "user", "content": "Summarize this supplier note in two sentences."}
  ],
  "max_tokens": 200
}

Same five slots, different contents: POST says "process this," the headers prove who you are and declare JSON, and the body carries the model name plus the messages array. If you did the Class 12 call, you have already sent exactly this envelope.

What connects to what you already know

The request body is just the JSON you met in Class 3, put inside an envelope. The model body is the mirror image of structured output from Part IV: there you told the model what shape to reply in; here you follow the shape the service demands. Same discipline — named fields, exact spelling, no improvisation.

Practical exercise: label a request

Read this request and label its five parts with a one-sentence purpose for each:

POST https://api.example-shop.com/v1/orders
Headers:
  Authorization: Bearer test-key-123
  Content-Type: application/json
Body:
{
  "customer_id": "cus_42",
  "items": [{"sku": "BE-WAFFLE-01", "qty": 2}],
  "currency": "EUR"
}

Finish line: a marked-up copy of the request where each of the five parts is labeled and has a one-sentence purpose ("the endpoint names…", "POST signals…", and so on).

Verify: cover your labels and ask: which line would change if you wanted a different customer? A different resource? A different identity? If you can answer all three, you see the envelope.

Common failure mode: calling the whole block "the API call" and stopping there. The exercise only counts if all five pieces are named separately — that separation is what lets you debug the next failure.

Check your understanding

1. What are the five parts of an API request? 2. Why does a GET usually have no body while a POST usually does? 3. Why do query parameters carry filters but never secrets? 4. What do the Authorization and Content-Type headers each tell the service? 5. If the method says POST but the endpoint docs say "retrieves a forecast," which one decides what actually happens — and why?