Chapter 02 — Make your first API calls4 min read

How APIs work

The restaurant model

The best way to understand how APIs work is to think about a restaurant.

You (the client) sit at a table. You don't walk into the kitchen to make your own food. Instead, you look at the menu, pick what you want, and tell the waiter. The waiter (the API) takes your order to the kitchen (the server), which prepares the food and sends it back through the waiter.

That's it. That's how APIs work:

  1. You send a request. "I want the pasta." In API terms: "Give me the user with ID 8421."
  2. The server processes it. The kitchen checks what you asked for, prepares it, and puts it on a plate.
  3. You get a response. The waiter brings back your dish. In API terms: you get a JSON object with the user's data.

You never see the kitchen. You don't know how the pasta is made. You just know what to ask for and what you'll get back. That's exactly how software talks to APIs.

Client, server, request, response

Let's put names on things. These four words will come up constantly.

Client: the one asking. It could be a mobile app, a website, a backend server, or even a spreadsheet with a plugin. Anything that sends a request is a client.

Server: the one answering. It receives the request, does some work (looks up data, processes a payment, sends an email), and sends back a response.

Request: the question. "What are Alice's permissions?" or "Create a new order" or "Cancel this subscription." A request always goes from the client to the server.

Response: the answer. Usually a JSON object with the data you asked for, or a confirmation that the action was performed. A response always goes from the server back to the client.

Every single API interaction follows this pattern. Uber asks Google Maps for directions: request. Google Maps sends back the route: response. Airbnb asks SendGrid to send an email: request. SendGrid confirms it was sent: response.

Endpoints: the menu

In a restaurant, the menu tells you what you can order. In an API, the equivalent is a list of endpoints.

An endpoint is a specific URL that does one specific thing. Think of each endpoint as a dish on the menu:

  • https://api.myapp.com/users → returns the list of all users
  • https://api.myapp.com/users/8421 → returns the profile of user #8421
  • https://api.myapp.com/orders → returns all orders
  • https://api.myapp.com/orders/5678 → returns the details of order #5678

Each URL points to a specific resource. You can't ask for something that doesn't have an endpoint. If there's no /invoices URL, you can't get invoices. When you're evaluating a third-party service, the list of endpoints tells you exactly what the API can and can't do.

This is why reading API documentation matters. It's the menu.

Try it yourself

An endpoint is just a URL. And a URL, you know how to open one.

wttr.in is a free weather service that exposes a public API. No account, no key, no setup. You give it a city name in the URL, it gives you back weather data as JSON. Perfect for our purposes.

Click the link below. It will open in a new tab:

👉 https://wttr.in/san+francisco?format=j1

You should see a wall of JSON. Don't worry about the size. Let's look at what you can recognize. Somewhere in the response, you'll find a current_condition object with values like:

{
  "temp_C": "15",
  "temp_F": "59",
  "humidity": "72",
  "windspeedKmph": "19",
  "windspeedMiles": "12",
  "weatherDesc": [{ "value": "Partly cloudy" }]
}

That's the current weather in San Francisco, as raw data. Notice that the API returns both metric and imperial units (temp_C and temp_F, windspeedKmph and windspeedMiles). A weather app takes exactly this JSON and turns it into a nice screen with icons and colors. But the data underneath is what you're looking at right now.

Now try changing the city name in the URL. Replace san+francisco with london, tokyo, or your own city. You'll get different data back, but the same structure. That's the beauty of an endpoint: same URL pattern, different input, same shape of response.

What just happened:

  • You are the client (your browser sent the request)
  • wttr.in is the server (it looked up the weather and sent back JSON)
  • The URL is the endpoint
  • The JSON you see is the response

That's an API call. You just made one.

Key takeaways

  • Every API interaction is a request (a question) and a response (an answer)
  • The client asks, the server answers
  • Endpoints are URLs. Each one points to a specific resource
  • An API call is not magic. You just did one by clicking a link