3. Mental models: restaurant, library, framework
Three mental models lock in everything that follows. The restaurant analogy makes the request-response cycle click. The business angle explains why every company has an API. The vocabulary split keeps you from confusing three terms that get used interchangeably.
The restaurant analogy
The best way to understand APIs is through a familiar analogy: ordering food at a restaurant.
You sit down at a restaurant. You're hungry, but you don't go into the kitchen, rummage through the refrigerator, and start cooking. Instead, you interact with an interface, the menu. The menu shows what the kitchen can make. You choose from the menu and tell the waiter your order. The waiter takes your request to the kitchen, the kitchen prepares your food, and the waiter brings back your order.
This is exactly how APIs work:
| Restaurant | API world | What it means |
|---|---|---|
| You (customer) | Your application | The program that needs something |
| Menu | API documentation | Lists what operations are available |
| Your order | API request | Asking for specific data or action |
| Waiter | The API | Takes your request, brings back the response |
| Kitchen | Server / database | Where the actual work happens |
| Your food | API response | The data or result you requested |
Just like you don't need to know how the kitchen works to order food, you don't need to understand a company's internal systems to use their API. The API is the clean interface that hides complexity. You make a request in a standardised way, and you get back a standardised response. Everything else (databases, business logic, infrastructure) is hidden from you, just like the kitchen is hidden from restaurant customers.
This abstraction is powerful. Spotify's recommendation algorithm could change completely tomorrow, but as long as their API still accepts "get recommendations for this user" and returns a list of songs, your app keeps working. The waiter might get a new chef in the kitchen, but your ordering experience stays the same.
Why companies build APIs
Companies don't build APIs out of kindness. They build them because APIs have become essential business strategy. Three common reasons explain many of the public APIs you'll meet in this book.
Reason 1: the platform effect
X (formerly Twitter) could build their own photo editor, video trimmer, and scheduling tool. Or they could provide an API and let thousands of developers build these tools instead. When developers build products that use X's API, X reaches more users without doing the work themselves.
The same pattern appears everywhere:
- Stripe: thousands of applications use Stripe for payments, making Stripe essential to e-commerce
- Google Maps: millions of websites use Google Maps, making Google indispensable for location services
- AWS: the cloud computing platform powers huge portions of the internet through its APIs
By providing an API, you create an ecosystem. Other developers extend your platform in ways you never imagined, and every integration makes your service more valuable.
Reason 2: revenue
APIs themselves are products. Companies make money by charging for API access:
- Twilio: charges per SMS message or phone call made through their API
- OpenAI: charges per token processed by GPT models through their API
- Google Maps: often inexpensive to start with, but charges for higher-volume API requests
- Weather APIs: basic data is free, premium forecasts require paid subscriptions
The API-as-a-product model lets companies monetise their infrastructure at scale. Instead of selling software licences, they sell access to capabilities, and every API call can generate revenue.
Reason 3: competitive advantage
Today, if your service doesn't have an API, developers will choose competitors who do. APIs are now table stakes. Companies that don't provide APIs:
- Can't integrate with other tools developers are using
- Can't automate workflows that developers need
- Can't scale to handle enterprise customers
- Lose deals to competitors with better integration options
The best services understand this. Slack, Salesforce, HubSpot, Shopify. Their success is partly because they built robust APIs early. Developers could integrate them into anything, which made them indispensable.
API vs library vs framework
"API" gets used loosely, which causes confusion. Three related but distinct concepts share the territory:
| Concept | What it is | Where it lives | Example |
|---|---|---|---|
| Web API | Interface to a remote service | On someone else's servers, accessed over the internet | OpenWeatherMap API, GitHub API, Stripe API |
| Library | Pre-written code you include | In your program, runs locally | requests, pandas, numpy |
| Framework | Structure that dictates how you build | Your code fits into its architecture | Django, Flask, React, Vue |
The shortest way to keep them straight: a web API means you make network requests to someone else's server, so it requires the internet (requests.get("https://api.example-weather.com/forecast")). A library is code you import that runs in your program with no network required (import pandas). A framework writes the rules: you fit your code into its structure, and it calls your code when needed (a Django web app where you define views that Django calls).
This book focuses on web APIs, services you access over the internet by sending requests and receiving responses. When the book says "API" from here on, it means web APIs unless specified otherwise.
Next, we'll open up the protocol that actually carries every web API request: HTTP.