APIs Explained: How Software Systems Talk to Each Other

Stripe Processes $1 Trillion Per Year Entirely Through APIs

Every time a business charges a credit card using Stripe, a few hundred lines of code make an API call. Stripe's servers receive the request, process the payment, and return a result — all in milliseconds. APIs (Application Programming Interfaces) are the connective tissue of the modern internet. They allow software systems built by different companies, in different languages, on different servers, to communicate as if they were a single system. Without APIs, Netflix couldn't send video to Samsung TVs, Uber couldn't show drivers on Apple Maps, and Spotify couldn't work through Alexa.

What an API Is

An API is a defined interface through which one piece of software exposes functionality or data to another. The term is broad — a function call in a library is technically an API. In web development, "API" almost always means a web API: an interface accessed over the internet using HTTP.

The analogy most developers use: a restaurant menu is an API. It specifies what you can order (available endpoints), what information you must provide (required parameters), and what you'll receive in return (response format). You don't need to know how the kitchen works. You just follow the interface.

REST: The Dominant Architecture

Representational State Transfer (REST) is an architectural style for designing web APIs. REST APIs have these characteristics:

Stateless: Each request contains all information needed to process it. The server doesn't remember previous requests — no server-side sessions.
Resource-based: Everything is modeled as a resource identified by a URL (Uniform Resource Locator). A user, an order, a product — each has a URL.
HTTP methods map to operations: GET (retrieve), POST (create), PUT/PATCH (update), DELETE (remove).
Uniform interface: Standard conventions for URLs, methods, and response formats.

HTTP Methods and What They Do

Method	Purpose	Idempotent?	Example
GET	Retrieve a resource	Yes	GET /users/42 — returns user with ID 42
POST	Create a new resource	No	POST /users — creates a new user with request body data
PUT	Replace a resource completely	Yes	PUT /users/42 — replaces user 42 with request body
PATCH	Partially update a resource	No	PATCH /users/42 — updates specific fields only
DELETE	Remove a resource	Yes	DELETE /users/42 — deletes user 42

HTTP Status Codes: The Response Language

Status codes communicate the result of every API request:

2xx — Success: 200 OK, 201 Created, 204 No Content
3xx — Redirect: 301 Moved Permanently, 304 Not Modified
4xx — Client Error: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 429 Too Many Requests
5xx — Server Error: 500 Internal Server Error, 503 Service Unavailable

Authentication and Authorization

Method	How It Works	Common Use Cases
API Keys	Client passes a secret key in headers or query params; server validates it	Server-to-server calls; public API access control
OAuth 2.0	Third-party authorization framework; user grants access; tokens issued	"Login with Google"; delegated user data access
JWT (JSON Web Token)	Signed token containing claims; server validates signature without database lookup	Modern auth; stateless session management
Basic Auth	Base64-encoded username:password in header	Simple server-to-server; internal APIs (always over HTTPS)

GraphQL: The Alternative to REST

GraphQL, developed by Facebook and open-sourced in 2015, is an alternative API query language and runtime. Key differences from REST:

Single endpoint: All requests go to one URL (e.g., /graphql). The query itself specifies what data is needed.
Client-specified response shape: The client declares exactly which fields it wants — no over-fetching (getting more data than needed) or under-fetching (requiring multiple calls to get needed data).
Strongly typed schema: The API schema explicitly defines all types, fields, and relationships — serving as documentation and enabling tooling.

GraphQL excels when different clients (mobile, web, third-party) need different subsets of the same data. It's more complex to implement server-side but solves common REST pain points for data-intensive applications.

Rate Limiting and API Design

Rate limiting prevents API abuse and ensures fair access across all clients. Common approaches:

Fixed window: N requests per time period (e.g., 1,000 requests per hour)
Sliding window: N requests in any rolling 60-minute window
Token bucket: A bucket refills with tokens at a fixed rate; each request consumes one token

Well-designed APIs include rate limit information in response headers (X-RateLimit-Remaining, X-RateLimit-Reset) so clients can adapt their behavior.

Webhooks: Callbacks vs. Polling

REST APIs are pull-based — the client must ask for data. Webhooks invert this: the server pushes data to the client when events occur. Instead of polling "did anything change?" every 30 seconds, you register a URL with the API provider. When a relevant event happens (payment processed, file uploaded, message received), the provider sends an HTTP POST to your URL with the event data. Webhooks are essential for real-time integrations.

API Versioning

APIs change over time. Versioning allows backward-incompatible changes without breaking existing integrations. Common strategies:

URL versioning: /api/v1/users (most common, most visible)
Header versioning: Accept: application/vnd.api+json;version=1
Query parameter: /users?version=1

Good API design minimizes breaking changes by adding fields rather than removing them, making new fields optional, and deprecating features with notice periods before removal.