APIs: How Software Talks to Other Software

Your Weather App Does Not Have a Satellite

When you check the weather on your phone, your weather app does not have a satellite. When you pay with Apple Pay, Apple does not process the payment. When you book an Uber, the app does not know traffic conditions -- Google Maps does. Every modern app is built by stitching together other companies' capabilities through APIs. An API is a contract: "Send me this data in this format, and I will send you back this response." Stripe processes $1 trillion in payments per year through its API. Twilio sends 150 billion messages per year. The API economy is bigger than most countries' GDP.

Understanding APIs is understanding how modern software is actually built. No company writes everything from scratch. They build their core product and plug into APIs for everything else: payments, maps, authentication, email, SMS, AI, weather, shipping, analytics. A single Uber ride involves more than 10 API calls to different services. A single Shopify checkout page talks to payment processors, tax calculators, shipping estimators, and inventory systems -- all through APIs. The app you see is the tip of the iceberg. The APIs underneath are the other 90%.

What an API Is, Without the Jargon

API stands for Application Programming Interface. That name is unhelpful. Here is what it actually means.

The restaurant analogy is common but worth extending because it maps precisely. An API is three things combined: a menu (documentation that tells you what you can request and in what format), a waiter (the HTTP request that carries your order to the kitchen), and kitchen rules (the server that processes your request, enforces permissions, and prepares the response). You never see the kitchen. You do not know how the chef prepares the food. You do not need to know. You just need to order correctly and the right dish arrives.

In technical terms: an API is a defined set of rules for how two pieces of software communicate. One piece (the client) sends a request. The other piece (the server) processes it and sends back a response. The rules specify what you can ask for, what format to use, what credentials you need, and what the response will look like.

Here is a real example. You want the current weather in London. You send a request to a weather API:

GET https://api.weatherapi.com/v1/current.json?key=YOUR_KEY&q=London

The server processes it and sends back:

{
  "location": {
    "name": "London",
    "country": "United Kingdom"
  },
  "current": {
    "temp_c": 14.0,
    "condition": {
      "text": "Partly cloudy"
    },
    "humidity": 72,
    "wind_kph": 19.1
  }
}

That response format is JSON (JavaScript Object Notation) -- the universal language of APIs. Key-value pairs, nested objects, arrays. Human-readable, machine-parseable. Virtually every modern API speaks JSON.

REST APIs: The Standard That Won

There are many ways to design an API. The one that dominates the modern web is REST (Representational State Transfer). REST is not a technology or a library -- it is an architectural style, a set of conventions that most APIs follow because they make communication predictable.

A REST API is organized around resources -- things you can interact with. Users, products, orders, messages. Each resource has a URL (called an endpoint), and you interact with it using standard HTTP methods that map to actions.

A real REST API for an e-commerce store might have these endpoints:

GET    /products          → List all products
GET    /products/42       → Get product #42
POST   /products          → Create a new product
PUT    /products/42       → Update product #42
DELETE /products/42       → Delete product #42
GET    /products/42/reviews → Get reviews for product #42

The URL structure is predictable. The methods are standard. If you understand one REST API, you can learn any other REST API in minutes because they all follow the same conventions. That predictability is why REST won.

The API Request/Response Cycle

Every API interaction follows the same cycle: the client builds a request, sends it to the server, the server processes it, and sends back a response. Understanding each step of this cycle is understanding how the modern web works at its core.

A request contains four parts. The method (GET, POST, PUT, DELETE) says what action you want. The URL/endpoint says which resource you are targeting. Headers carry metadata: your authentication token, the content type, caching instructions. The body (for POST and PUT requests) carries the actual data you are sending.

A response contains two critical parts. The status code tells you what happened -- it is the first thing you check. The body contains the actual data, almost always in JSON format.

Status codes you need to know

Status codes are three-digit numbers grouped by category. The first digit tells you the category:

When something goes wrong with an API call, the status code is your first diagnostic clue. A 401 means fix your authentication. A 429 means slow down. A 500 means wait and retry -- the problem is on their end, not yours.

Authentication: Proving You Are Allowed

Most APIs are not open to the public. They need to know who is making the request, whether they are allowed to make it, and sometimes how many requests they have made. This is authentication, and there are three common approaches.

API keys: the simplest method

An API key is a long string that identifies your application. You include it in every request, either as a query parameter or in a header. The weather API example above used an API key (key=YOUR_KEY). It is simple, but an API key is like a house key: anyone who has it can use it. If it leaks (committed to a public GitHub repo, embedded in client-side JavaScript), anyone can make requests on your behalf, run up your bill, or access your data.

OAuth 2.0: what "Sign in with Google" uses

When you click "Sign in with Google" on a website, you are using OAuth. The flow is more complex than API keys but solves a critical problem: it lets a third-party app access your data without ever seeing your password.

Bearer tokens: session-based access

After authenticating (whether via OAuth, a username/password login, or another method), the server issues a token -- a string that proves you are authenticated. You include this token in the Authorization header of every subsequent request: Authorization: Bearer eyJhbGciOiJIUz.... Tokens typically expire after a set period (1 hour, 24 hours) and must be refreshed, which limits the damage if one is stolen.

Building with APIs: A Real Example

To make this concrete, here is the same API call in three formats. You want to fetch the current weather in London from a public API.

const response = await fetch(
  'https://api.weatherapi.com/v1/current.json?key=YOUR_KEY&q=London'
);
const data = await response.json();

console.log(data.current.temp_c);
// Output: 14.0

import requests

response = requests.get(
    'https://api.weatherapi.com/v1/current.json',
    params={'key': 'YOUR_KEY', 'q': 'London'}
)
data = response.json()

print(data['current']['temp_c'])
# Output: 14.0

Both examples do the same thing: send a GET request, receive JSON, extract the temperature. The pattern is identical regardless of language. Learn it once, apply it everywhere.

Popular APIs You Have Used Without Knowing

APIs are invisible to end users by design. But they power every digital experience you have.

Google Maps API -- every "Find us" map on a restaurant website, every ride-sharing app's driver location view, every real estate listing with an interactive map. Google charges per API call (roughly $7 per 1,000 map loads), which is why some small businesses use OpenStreetMap as a free alternative.

Stripe API -- every "Pay Now" button on sites from Shopify stores to SaaS platforms. Stripe handles payment processing, fraud detection, tax calculation, and invoicing through a single API. A developer can add payments to their app in a few hours by calling Stripe's API rather than spending months building a payment system from scratch and navigating PCI compliance.

OpenAI API -- every AI chatbot you have encountered outside of ChatGPT's own interface is likely calling OpenAI's API. Customer support bots, coding assistants, content generators -- they send your prompt to OpenAI's servers and receive the AI's response via API. The API processes billions of requests per month.

Twilio API -- every SMS verification code you have ever received ("Your code is 847291") was almost certainly sent through Twilio or a similar messaging API. The website does not have access to your phone carrier. It calls Twilio's API with your phone number and the message, and Twilio handles delivery.

SendGrid/Mailgun API -- every transactional email (order confirmations, password resets, shipping notifications) is sent through an email delivery API. Companies do not run their own email servers anymore. They call an API, pass the recipient, subject, and body, and the service handles delivery, bounce tracking, and spam compliance.

Rate Limits, Errors, and Real-World Gotchas

APIs in production are not as smooth as tutorials make them seem. Here are the problems every developer encounters.

Rate limiting

Every API limits how many requests you can make in a given time window. Twitter's API allows 300 requests per 15 minutes for some endpoints. OpenAI's API limits by tokens per minute. When you exceed the limit, you get a 429 Too Many Requests response. The fix: add delays between requests, cache responses you have already received, and implement exponential backoff (wait 1 second, then 2 seconds, then 4 seconds before retrying).

Timeouts

Sometimes the server does not respond at all. Your code needs to handle this: set a timeout (typically 5-30 seconds), and if no response arrives, either retry or fail gracefully with an error message to the user. Never let your application hang indefinitely waiting for an API response.

API versioning

APIs change. Endpoints get renamed, response formats get restructured, features get deprecated. Good APIs version their URLs (/v1/users, /v2/users) so that changes do not break existing applications. Bad APIs change without warning. Always pin to a specific API version in production and subscribe to the API provider's changelog.

Beyond REST: GraphQL and WebSockets

REST dominates, but it has limitations that two alternative approaches address.

GraphQL: ask for exactly what you need

Facebook created GraphQL in 2012 to solve a specific problem with their mobile app. The REST API returned way too much data for simple requests (a user profile endpoint might return 50 fields when the mobile app only needed 3) or required too many separate requests (load a post, then its comments, then the commenter profiles -- three round trips).

GraphQL lets the client specify exactly which fields it wants in a single request:

query {
  user(id: 42) {
    name
    avatar
    posts(last: 5) {
      title
      commentCount
    }
  }
}

One request. Exactly the data you need. No over-fetching, no under-fetching. GitHub, Shopify, and Yelp use GraphQL for their public APIs.

WebSockets: real-time two-way communication

REST and GraphQL follow a request-response pattern: the client asks, the server answers. But some applications need the server to push data to the client without being asked. Chat applications, live sports scores, multiplayer games, stock tickers, collaborative editing (Google Docs) -- all of these need real-time, two-way communication.

WebSockets open a persistent connection between client and server. Either side can send a message at any time. There is no request-response cycle -- data flows freely in both directions. When someone sends you a message on Slack, the server pushes it to your client through a WebSocket connection instantly, without your client needing to poll "any new messages?" every second.

How a Single Uber Ride Uses 10+ API Calls

To see how APIs compose in the real world, trace the lifecycle of a single Uber ride.

Seven distinct API integrations for a single ride. Uber did not build maps, payments, email delivery, or real-time location tracking from scratch. They built the ride-matching logic and plugged into best-in-class APIs for everything else. This is the API economy: companies specialize in one thing and expose it as an API. Other companies compose those APIs into products. Everybody benefits.

Answers to Questions Students Actually Ask

Can I use APIs for free? Many APIs have free tiers. OpenWeatherMap gives you 1,000 calls per day free. The News API gives you 100 requests per day. Google Maps gives you $200 of free usage per month. For learning and small projects, free tiers are usually enough. For production applications with real users, you will need a paid plan. API pricing is typically per-request (pay for what you use), which scales naturally with your application's growth.

How do I find APIs to use? Start with the Public APIs directory on GitHub -- it lists thousands of free APIs organized by category. RapidAPI is a marketplace with 40,000+ APIs. For specific needs (payments, email, SMS), the dominant provider's documentation is usually the best starting point: Stripe for payments, Twilio for messaging, SendGrid for email.

What happens if an API I depend on goes down? Your application breaks. This is a real risk. Twitter's API restrictions in 2023 killed hundreds of third-party apps overnight. Mitigation strategies: cache API responses so your app can serve stale data during outages, use multiple providers for critical functions (a backup email service if SendGrid goes down), and build fallback behavior (show a static map instead of crashing if Google Maps is unavailable).

Is it hard to build my own API? Simpler than you think. A basic API in Node.js (Express) or Python (Flask/FastAPI) can be built in under 100 lines of code. The complexity scales with features: authentication, rate limiting, validation, documentation, database connections, error handling. But a functional API that accepts requests and returns JSON? An afternoon project.

REST or GraphQL? Start with REST. It is simpler, more widely supported, and what 95% of the APIs you will interact with use. Learn GraphQL when you encounter a specific problem it solves (usually mobile apps that need to minimize data transfer or applications that stitch together many data sources in a single query). You do not need GraphQL for your first five projects.

Where APIs Take You Next

APIs connect everything in modern software. Understanding them unlocks nearly every other topic in this field. Backend development is fundamentally about building APIs -- designing endpoints, handling requests, querying databases, and returning responses. Frontend development means consuming APIs -- fetching data and rendering it on screen. Mobile development is the same: every screen in a mobile app loads its data from APIs. DevOps automates infrastructure through APIs (AWS, Azure, and Google Cloud are API-first platforms). Data engineering extracts data from APIs, transforms it, and loads it into warehouses.

The mental model is powerful: every application is a client to some APIs and a server for others. Your frontend is a client to your backend API. Your backend is a client to Stripe's payment API and Google's Maps API. Stripe's servers are clients to bank APIs. It is APIs all the way down. Understanding that pattern means understanding how the modern internet's software ecosystem is assembled -- not as monolithic applications, but as networks of specialized services communicating through well-defined contracts.