Anatomy of a request

What's inside a request?

In the previous lesson, you made your first API call by clicking a link. Your browser sent a request to wttr.in and got back JSON. Simple.

But that request contained more than just a URL. Every API request has a few key parts, and understanding them will help you read API docs, write better specs, and have more productive conversations with your engineers.

The URL (where to go)

You already know this part. The URL tells the server what you're asking for. Let's use a public API called DummyJSON that provides fake user data (useful for testing and learning):

• The base URL is the address of the server, like a street address for a building.
• The path tells the server which specific resource you want. Here, /users means "the users endpoint."
• The query parameter is extra instructions. limit=2 tells the server "just give me two users."

Try it: 👉 click here to open this API in a new tab

You should see a JSON response with two users (name, email, age, etc.). Now the fun part: query parameters let you customize what you get back. You can stack them with &:

This says: "Give me 3 users, but only their name, email, and age, sorted by age from oldest to youngest." Same endpoint, different parameters, different output.

Try it: 👉 open this URL in a new tab and compare with the first one. The structure is identical, but the data is filtered and sorted.

Query parameters are how you filter, sort, and customize what you get back from an API. You'll see them everywhere.

The method (what to do)

The URL says where to go. The method says what to do when you get there.

There are four methods you'll see all the time:

GET: read data. "Give me the list of users." This is the most common one. When you typed a URL in your browser, you were sending a GET request. Every time you load a webpage, that's a GET. In fact, a browser can only send GET requests. It's built for reading, not for creating or deleting.

POST: create something. "Create a new order." You're sending data to the server and asking it to create a new resource.

PUT: update something. "Update user #8421's email address." You're modifying an existing resource.

DELETE: remove something. "Cancel order #5678." You're asking the server to delete a resource.

For POST, PUT, and DELETE, you need a tool that lets you choose the method. Engineers use tools like Postman or similar. We'll explore that in a later chapter.

Think of it this way. The same endpoint can do different things depending on the method:

The URL is the same. The method changes the meaning entirely. It's like the difference between looking at a document, editing it, or deleting it.

The headers (metadata)

Headers are extra information attached to the request. They don't contain the actual data you're asking for. They describe how the request should be handled.

The most common ones you'll see in API docs:

• Content-Type: application/json tells the server "the data I'm sending is JSON"
• Authorization: Bearer sk_live_abc123 tells the server who you are (we'll cover this in the authentication chapter)
• Accept: application/json tells the server "please send me JSON back"

You don't usually set headers manually. The app or tool you're using handles them. But you'll see them in API documentation, and now you know what they are: metadata about the request, not the request itself.

The body (the data you send)

Not every request has a body. When you GET data, you're just asking a question. There's nothing to send.

But when you POST or PUT, you're sending data to the server. That data goes in the body of the request. And it's usually JSON.

For example, to add a new user to DummyJSON:

With this body:

You're telling the server: "Create a new user with this name, this email, and this age." The server processes it and sends back a response (usually the created user with an id that was generated for it).

Putting it all together

Here's what a complete API request looks like, all parts included:

Read it like a sentence: "Create (POST) a new order (/orders) for this customer with these items (body), and here are my credentials (Authorization header)."

That's a full request. URL, method, headers, body. Now when you see these in API docs, you'll know exactly what each part does.

Key takeaways

• The URL says where to go (base URL + path + query parameters)
• The method says what to do (GET, POST, PUT, DELETE)
• Headers are metadata about the request (authentication, content type)
• The body carries the data you're sending (used with POST and PUT, always in JSON)