APIs: How Software Talks to Software
Behind almost every tool an AI agent uses is a technology called an API. The word stands for Application Programming Interface, which sounds intimidating, but the idea is simple enough to explain with a restaurant analogy. Understanding APIs is not optional if you want to understand how agents work — they are the invisible plumbing that connects an agent's requests to the real world.
The Restaurant Analogy
Imagine a restaurant. You are the customer. The kitchen is a powerful system full of chefs who can make hundreds of dishes. You cannot walk into the kitchen and start cooking — that would be chaos. Instead, there is a waiter. You tell the waiter what you want (your request). The waiter takes that request to the kitchen in a specific format the kitchen understands. The kitchen prepares the order and gives the result back to the waiter. The waiter delivers it to your table. An API is the waiter. You are the software making the request (in our case, the AI agent). The kitchen is the external service (a weather database, a mapping system, a calendar app). The API defines the exact format for placing an order — what you can ask for, how to ask for it, and what format the answer will come back in. You never see the kitchen's internal workings. You just get your meal.
An API is a defined set of rules that lets one software program request services from another. It specifies exactly how to make a request and what format the response will take — hiding internal complexity from the requester.
Requests and Responses
Every API interaction has two sides: a request and a response. The request is sent by the client — the software that wants something. It specifies what action to take and provides any needed parameters. A weather API request might say: action = get_forecast, city = Seattle, days = 3. The response is sent back by the server — the software that provides the service. It returns the result in a structured format, typically JSON (JavaScript Object Notation), which looks like organized labeled data. The response might contain temperature, humidity, wind speed, and a three-day forecast — all neatly labeled so the agent can read exactly the field it needs. This request-response cycle is the heartbeat of the modern internet. Every time you check your email, view a map, or stream a video, dozens of API calls are happening in the background.
JSON (JavaScript Object Notation) is a lightweight format for organizing data as labeled key-value pairs. Most APIs return JSON because it is easy for any programming language to read. An agent reading API output is essentially reading structured JSON.
API Keys: Proving Who You Are
Most real-world APIs do not let just anyone use them for free and without limits. Before your software can use them, you must prove who you are and agree to rules about how much you can use. This proof comes in the form of an API key — a long secret string of characters that acts like a password for your software. When an agent calls a tool that uses an external API, that tool includes the API key in the request so the service knows who is asking. API keys let service providers track usage, enforce limits, and charge for heavy use. They also mean that if someone steals your key, they can use the service as if they were you — which is why keys must be kept secret and never hard-coded in public code.
An API key is like a password for your software. Sharing it publicly or accidentally exposing it in code gives anyone the ability to use the service as you — running up costs or triggering actions you did not authorize.
Match each API concept to its correct description.
Terms
Definitions
Drag terms onto their definitions, or click a term then click a definition to match.
In the restaurant analogy for APIs, what does the waiter represent?
Why does an AI agent's search tool include an API key when it contacts a search service?
Trace an API Call
- Step 1: Imagine an AI agent is helping you plan a trip. It needs to know the current weather in Paris. Trace the full API call by answering these questions in writing:
- A) Who is the client (the one making the request)?
- B) What is the request? Write it out as labeled fields: action, city, units.
- C) Who is the server (the one receiving the request)?
- D) What would a reasonable JSON response look like? Make up realistic labeled data.
- Step 2: Now imagine the weather API requires an API key. Add the key field to your request. Make up a fake key like 'wx_fake_abc123'.
- Step 3: What would happen if you forgot to include the API key? Write the likely error message the server would return.
- Step 4: In two sentences, explain why understanding APIs helps you understand how AI agents work.