# What an API Actually Is > An API is a defined way for one program to ask another for something - a contract that says what you can ask and what you'll get back - and this guide builds that mental model from the ground up before you touch any code. --- # What an API Actually Is You've seen "API" everywhere - "we have an API," "call the payments API," "the API is down." Maybe you've nodded along while quietly wondering what the word actually *means*, and whether everyone else is in on something you missed. You're not missing anything. "API" is one of those terms people use constantly and define rarely. Here's the good news: the idea underneath it is genuinely simple, and once it clicks, a huge amount of how modern software fits together suddenly makes sense. This guide builds that idea slowly and properly - no jargon dropped on you undefined, no hand-waving. By the end you'll read "we'll integrate with their API" and know exactly what that sentence promises. ## How to read this - **Want it to finally make sense?** Read in order. Each phase builds on the last - we install the core idea first, then *why* it exists, then the different shapes it comes in. - **Already know the basics and want the lay of the land?** Skip to [Phase 3: Kinds of APIs](03-kinds-of-apis.md) for the map of library APIs vs web APIs and where REST/GraphQL/gRPC fit. ## The phases 1. **[A Contract Between Programs](01-a-contract-between-programs.md)** - what an API *actually is*: a defined way to ask another program for something, with the internals hidden. The restaurant-menu mental model. 2. **[Why APIs Exist](02-why-apis-exist.md)** - the real reasons they're everywhere: reuse, separation, and integration - and why a stable boundary is so valuable. 3. **[Kinds of APIs](03-kinds-of-apis.md)** - local/library APIs vs web APIs over the network, a preview of the common web styles (REST, GraphQL, gRPC), and where to go next. > This guide deliberately stops at the mental model. It does *not* teach you to make HTTP requests, read JSON, or design a REST endpoint - those get their own guides, linked at the end, so this one stays a clean, calm foundation. --- # A Contract Between Programs Before any acronym, let's build the one idea everything else rests on. Forget code, forget the internet, forget the word "API" for a minute. We're going to a restaurant. ## The menu, the waiter, and the kitchen You sit down. Someone hands you a **menu**. The menu lists what you can ask for and what you'll get: "Margherita pizza - tomato, mozzarella, basil." You don't walk into the kitchen. You don't need to know whether the chef uses a wood oven or a gas one, where they buy the cheese, or how many cooks are back there. You read the menu, you place an order with the waiter, and a while later the pizza arrives. That whole arrangement is the idea behind an API. ```mermaid sequenceDiagram participant You as You (customer) participant Waiter as Menu + Waiter (the agreed way to ask) participant Kitchen as Kitchen (does the real work) You->>Waiter: "I'd like a margherita" Waiter->>Kitchen: passes your order back Kitchen-->>Waiter: chef cooks it (you never see how) Waiter-->>You: brings out the pizza ``` - **You** are one program that needs something done. - **The kitchen** is another program that knows how to do it. - **The menu and the waiter** are the API: the agreed-upon way you ask, and the agreed-upon thing you get back. The kitchen could be tiny or enormous. It could change chefs tomorrow. As long as the menu still says "margherita pizza" and a margherita pizza still arrives when you order one, *you don't care what changed back there.* That not-caring is the whole point. ## What an API actually is An **API** - Application Programming Interface - is a **defined way for one program to ask another program for something.** It spells out two things: what requests you're allowed to make, and what you'll get back for each one. It is, at heart, a **promise**: "ask me *this*, in *this* way, and I'll give you *that*." 📝 **Terminology.** *API* stands for **Application Programming Interface**. Don't let the words intimidate you - "interface" here means the same thing it means on a TV remote: the agreed set of buttons you're allowed to press. The remote is the interface to the television; you press a button, something happens inside, and you never open the case. An API is the set of "buttons" one program exposes for other programs to press. The most common wrong picture is thinking an API is *the other program itself* - "the payments API" must be the whole payment system, right? It isn't. The API is the **menu**, not the kitchen. It's the thin, public, agreed-upon front of a much bigger thing you never see. The payment system might be a million lines of code across hundreds of machines; the API is the short list of things you're allowed to ask it to do. When developers say "the weather app uses a weather API," here's the literal sequence: the app sends a request that follows the menu ("give me today's forecast for London"), some other system does the real work (reads sensors, runs models, looks up data), and sends back a tidy answer the app knew to expect. The app never runs the weather models. It orders from the menu. ## The two halves of the promise Every API is really two agreements, and it helps to see them separately: ```text ┌─────────────────────────────┐ │ WHAT YOU CAN ASK │ "You may request today's forecast │ (the requests allowed) │ for any city, by name." ├─────────────────────────────┤ │ WHAT YOU GET BACK │ "You'll get a temperature, a │ (the response promised) │ condition, and a chance of rain." └─────────────────────────────┘ together = the contract ``` This is why people call an API a **contract**. A contract is a promise both sides can rely on. The program offering the API promises: "if you ask in this exact way, I'll respond in this exact way." The program using it promises: "I'll only ask in the agreed way, and I'll expect the agreed answer." Neither side has to know how the *other* side is built internally - they only have to honor the contract between them. 💡 **Key point.** An API is a **contract**: a defined set of requests you can make and responses you'll get back. The work behind it is hidden on purpose. You program *against the menu*, not against the kitchen. ## Hiding the internals is the feature, not a limitation It's tempting to feel like the hidden kitchen is something being kept *from* you. Flip that around - the hiding is doing you an enormous favor. Because the internals are hidden, the team running the kitchen can rip out the old oven, hire new cooks, or rewrite the whole thing in a different language, and **your order still works** - as long as they keep honoring the menu. You wrote your program to depend on the *promise*, not on the *plumbing*. That's what lets two pieces of software, built by different people who never met, work together reliably for years. 📝 **Terminology.** This deliberate hiding has a name: **abstraction.** To "abstract away" the kitchen means to give you a simple way to use it (the menu) without exposing the complicated reality behind it. APIs are one of the main ways software hides complexity so humans can build big things without holding all the details in their heads at once. Once you see an API as a contract that hides a kitchen, a lot of developer sentences decode themselves. "Don't break the API" means *don't change the menu out from under the people who ordered from it.* "That's not exposed in the API" means *the kitchen can do it, but the menu doesn't offer it to you.* "We're versioning the API" means *we're publishing a new menu without yanking the old one away from existing customers.* ## Recap 1. An API is a **defined way for one program to ask another for something** - the menu and waiter, not the kitchen. 2. It's a **contract** with two halves: what you can ask, and what you'll get back. 3. The internals are **hidden on purpose** (abstraction) - that's what lets the other side change without breaking you. 4. You program **against the promise**, not against the inner workings, which is exactly why independently-built software can work together. Next, we'll ask the obvious question: if an API is a contract that hides a kitchen, *why* is software built this way at all? What problem does the whole arrangement solve? --- # Why APIs Exist In Phase 1 we built the picture: an API is a contract that hides a kitchen. Fair enough - but *why* build software this way? Why not have each program just do everything itself? The answer is three real problems that APIs solve, and they show up constantly. Once you can name them, you'll spot APIs doing their job all over the software you already use. ## Reason 1: Reuse - don't rebuild the kitchen Imagine you're building an app that needs a map. To do it yourself, you'd have to gather road data for the entire planet, keep it updated as roads change, draw the tiles, calculate driving routes... it's not a feature, it's a decade-long company. So you don't. You use a maps **API** offered by someone who already did all that. Your app asks "draw a map centered here" or "give me directions from A to B," and their system does the heavy lifting. You got a planet's worth of map work for the cost of placing an order from a menu. ```text WITHOUT an API WITH an API ────────────── ─────────── build maps yourself ask a maps service build payments yourself ask a payments service build email sending yourself ask an email service (years of work each) (a request each) ``` This is why you almost never see an app handle credit cards by writing its own banking code. Money is hard and dangerous to get right, so apps use a payments API (the well-known one is Stripe) and let a specialist's system do the risky part. The app's job shrinks to *placing the order correctly.* 💡 **Key point.** An API lets you **reuse someone else's hard work** without rebuilding it - and without even understanding how they did it. The menu is all you need. ## Reason 2: Separation - a clean line through your own software APIs aren't only for talking to *other* companies. They're also how a single app keeps its own halves from becoming a tangled mess. Most apps you use have two big parts. There's the part you see and touch - the screens, the buttons, the layout - and there's the part that holds the real data and rules behind the scenes. 📝 **Terminology.** The visible part is the **frontend** (what runs in your browser or phone - the buttons and screens). The behind-the-scenes part is the **backend** (the server that stores data, checks passwords, enforces the rules). "Front" and "back" are literal: front is what faces the user, back is what's kept in back. These two halves talk to each other through - you guessed it - an API. ```mermaid sequenceDiagram participant Frontend as Frontend (the screen you touch) participant Backend as Backend (data, rules, passwords) Frontend->>Backend: "log this user in" Backend-->>Frontend: "ok, here's their name and inbox" ``` When you log in, the frontend doesn't check your password itself - it sends your details across this API to the backend and asks "is this person allowed in?" The backend does the checking and answers. Because there's a clean contract between them, two different teams can work on the two halves at once, and either side can be rebuilt without dragging the other along - as long as the contract holds. Beginners often picture an app as one single blob of code. Most real apps aren't; they're a frontend and a backend that *only* communicate through an agreed API. Knowing this line exists explains a lot - like why a website can change its entire look overnight while your data and login stay exactly the same. They changed the frontend; the backend and the contract between them didn't move. ## Reason 3: Integration - plugging into someone else's service The third reason is the one that makes the modern software world feel connected: **integration.** When your app uses another company's service through its API, the two are "integrated." This is how a small app can suddenly do big things. It posts to social media (through the platform's API), sends text messages (through a messaging API), checks the weather, looks up a shipment, charges a card - all by being a polite customer at other companies' menus. Your app becomes a coordinator that knows *which kitchens to order from*, rather than a place that cooks everything. 🪖 **War story.** A team I knew once seriously debated building their own email-sending system - handling spam filters, bounced addresses, the lot. They estimated months of work. Instead they integrated with an email API in an afternoon and shipped that week. The lesson stuck: before building a "kitchen," check whether someone already runs one and put a menu out front. ## The idea underneath all three: a stable boundary Reuse, separation, integration - they look like three different things, but they're all the same trick. An API draws a **stable boundary** between two pieces of software. On your side of the boundary, you only have to know the contract. On the other side, they're free to change everything *except* the contract. ```text YOUR SIDE │ THEIR SIDE ────────────────────────┼──────────────────────── you depend only on │ they can rewrite, the contract (the menu) │ rebuild, rehire, rehouse │ - anything but the menu ───────────────────┴─────────────────── the API = the line you both agree not to cross ``` This is why a boundary is so valuable. Software changes constantly - bugs get fixed, systems get rewritten, companies move things around. A stable API is the one thing both sides promise *not* to yank around. It lets the kitchen evolve while every customer who ordered from the menu keeps getting their pizza. ⚠️ **Gotcha.** That promise is exactly why **breaking an API is a big deal.** If a service changes its menu - renames a request, drops a field from the response - every app that depended on the old menu can break at once, often without warning. This is the reason serious APIs go to great lengths to keep old contracts working (you'll hear this called "versioning"), and why "we broke the API" is something engineers say in a lowered voice. When you hear "we expose that through an API," "the frontend calls the backend," or "we integrated with their API," you'll now hear the *reason* underneath: someone wanted to reuse work, separate two halves, or plug into a service - by drawing a stable boundary they could depend on. That's the whole game. ## Recap 1. **Reuse** - use someone else's hard work (maps, payments, email) instead of rebuilding it. 2. **Separation** - the frontend and backend of one app talk through a clean API line, so each can change independently. 3. **Integration** - your app plugs into other companies' services through their APIs. 4. All three are the same idea: an API is a **stable boundary** you depend on while the other side is free to change - which is exactly why breaking it matters so much. Next, we'll get concrete about the *kinds* of APIs you'll meet - the ones living inside your own program versus the ones you reach across a network - and name the styles you'll keep hearing about. --- # Kinds of APIs You've got the core idea now: an API is a contract that hides a kitchen, and it exists to let software reuse, separate, and integrate. The word "API," though, gets used for two genuinely different situations, and conflating them is a common source of quiet confusion. Let's split them cleanly, then name the styles you'll keep hearing about so they stop sounding like a secret language. ## The big split: local vs over-the-network Every API falls on one side of a simple line - **is the kitchen in the same building as you, or across town?** ```text ┌─────────────────────────────┐ ┌─────────────────────────────┐ │ LIBRARY / LOCAL API │ │ WEB API │ │ │ │ │ │ the other "program" is │ │ the other program is on │ │ code already inside YOUR │ │ a different machine, │ │ program - same building │ │ reached over the network │ │ │ │ │ │ the call is instant and │ │ the request travels across │ │ free; no network involved │ │ the internet and back │ └─────────────────────────────┘ └─────────────────────────────┘ ``` ### Library APIs - the kitchen is in your own house A **library** is a chunk of pre-written code you pull into your program to reuse. It exposes an API: a set of functions you're allowed to call. 📝 **Terminology.** A *library* is reusable code someone else wrote that you include in your own program - for example, code that knows how to do date math, or compress an image. Its API is the list of functions it lets you call. When you call a library function, nothing leaves your machine. It's like ordering from a kitchen *in your own house* - the menu still hides how it works, but the food arrives instantly because nothing had to travel anywhere. Calling `round(3.7)` to round a number, or asking a date library "what's 30 days from today?" - those use library APIs. Same contract idea, no network. ### Web APIs - the kitchen is a restaurant across town A **web API** is the kind most people mean when they say "API" today. Here the other program lives on a *different machine* - a server somewhere on the internet - and your request has to **travel over the network** to reach it and travel back with the answer. 📝 **Terminology.** A *web API* (also called a *remote* API) is an API you reach over a network rather than from code inside your own program. The weather, maps, and payments examples from earlier are all web APIs. That journey across the network changes things in ways worth knowing up front: - **It takes time.** A round trip to a server is far slower than calling code in your own program. Not slow like watching paint dry - but slow enough that it matters. - **It can fail.** The network can drop, the other server can be down or busy. A library call in your own house can't "fail to arrive"; a request across town can. - **It needs an address and rules.** To reach a kitchen across town, you need its address and an agreed language for placing orders. ⚠️ **Gotcha.** This is the single biggest difference to internalize: a **web API call can be slow and can fail**, where a local function call effectively can't. A lot of real-world bugs and confusion come from treating a request across the internet as if it were as instant and reliable as calling code next door. It isn't. Code that talks to web APIs has to expect waiting and has to expect failure. **This category - `apis` - is about web APIs.** Library APIs are real and everywhere, but when this part of The Missing Manual says "API," it means the over-the-network kind, because that's where most of the questions, the integrations, and the 2am incidents live. ## The styles of web API (a preview, not a lesson) Once two programs talk across a network, they need a shared *style* for how requests and responses are shaped - the agreed language for placing orders. You'll hear a few names. Here's just enough to recognize them; each is its own topic for later. | Style | The one-line gist | You'll hear it called | |---|---|---| | **REST** | Treat everything as a "resource" (a user, an order) you fetch and change with simple, standard actions. The most common style on the public web. | "a REST API," "RESTful" | | **GraphQL** | The caller describes *exactly* the data it wants in one query, and gets back that shape - no more, no less. | "a GraphQL API" | | **gRPC** | A fast, compact style aimed at programs talking to programs at high volume, often *inside* a company rather than on the public web. | "gRPC," "a gRPC service" | Don't memorize these. The only thing to take away right now is that **"web API" isn't one single thing** - it's a family with a few common dialects, and REST is the one you're most likely to meet first. When you read "they have a REST API," you can now translate it: *they offer a contract you call over the network, in the most common style.* 💡 **Key point.** Two splits, in order: first **local vs over-the-network** (library API vs web API); then, within web APIs, a few **styles** (REST, GraphQL, gRPC). Get the first split solid; treat the styles as names to grow into. ## Where to go next You now have the whole mental model: what an API is (a contract that hides a kitchen), why it exists (reuse, separation, integration - a stable boundary), and the kinds you'll meet (local vs web, and the web styles). That's the foundation this category is built on. The natural next step is to see a web API actually *work* - how a request travels, and what the answer looks like when it comes back. Almost every web API speaks over **HTTP** and answers in **JSON**, so that's where to head: - **[HTTP and JSON API basics](/guides/http-and-json-api-basics)** - how a web request and its response are actually shaped. Read this next. - **[HTTP explained](/guides/http-explained)** - a deeper look at the protocol the whole web (and most web APIs) runs on. - **[REST APIs explained](/guides/rest-apis-explained)** - once HTTP and JSON make sense, this unpacks the most common web-API style in full. ## Recap 1. APIs split first into **library/local** (the kitchen is in your own program; calls are instant) and **web** (the kitchen is across the network; requests travel and take time). 2. Web API calls are **slower and can fail** in ways local calls can't - internalize that early. 3. This category focuses on **web APIs.** 4. Web APIs come in a few **styles** - REST (most common), GraphQL, gRPC - which are names to recognize now and learn later. 5. Next stop: how a web request and response are actually shaped, over **HTTP and JSON**.