The Menu — Endpoints

Lesson 2 · taught by Pip

In the last lesson, the API was the menu and the waiter together. Now let's zoom in on the menu itself, because that's where you decide what to order.

A real menu doesn't say "food." It lists specific dishes: soup, burger, salad. Each one is a separate, named thing you can ask for. An API works the same way. Each specific thing you're allowed to request is called an endpoint.

What an endpoint is

An endpoint is one specific request an API offers — a single line on the menu.

A weather service, for example, doesn't just offer "weather." It offers separate dishes:

• one endpoint for today's weather in a city
• one endpoint for the five-day forecast
• one endpoint for yesterday's record temperatures

Each is its own line item. You pick the one that matches what you actually want, the same way you'd point at soup rather than vaguely asking for "something warm."

Endpoints have addresses

Here's the one new wrinkle. On a paper menu, you point with your finger. With an API, you point with an address — a web link, the same kind of thing you type into a browser.

An endpoint's address might look like this:

https://api.weather-example.com/today

Read it like a street sign. api.weather-example.com is the building — the weather service's front door for apps. /today is the specific room inside it — the "today's weather" counter. Change the ending and you walk to a different counter:

https://api.weather-example.com/forecast

Same building, different room, different dish. Each distinct ending is a distinct endpoint.

Telling the endpoint what you mean

A waiter taking your burger order asks follow-ups: how do you want it cooked? An endpoint does the same. You add little notes to your request to make it specific.

For a weather endpoint, the obvious note is which city. That extra detail rides along on the end of the address, after a question mark:

https://api.weather-example.com/today?city=Boston

The ?city=Boston is your follow-up answer: "today's weather — for Boston, please." These tacked-on notes have a name we'll use throughout the course: parameters. For now, just see them as the "how would you like that?" part of the order. Different city, same endpoint:

https://api.weather-example.com/today?city=Denver

Reading a menu before you order

Good news: API menus are written down. Every serious API publishes a page called documentation — "the docs" — that lists every endpoint, what each one returns, and which notes it expects. It's the menu with descriptions under each dish.

You don't memorize an API. You read its docs the way you'd skim a menu: find the dish you want, check what it comes with, then order. 🔦

Your turn

Imagine a maps service. Without looking anything up, sketch three endpoints it might offer — three separate dishes on its menu. Maybe one for directions between two places, one for nearby coffee shops, one for the name of an address.

For each, jot down the one or two notes (parameters) it would need from you. You're learning to read a menu before you ever place an order. Next, we'll actually send one.