API
Application Programming Interface: a contract defining how two pieces of software talk to each other. The waiter between your frontend and your backend.
What is API?
In short
An API (Application Programming Interface) is a defined set of rules that lets one piece of software request data or actions from another without knowing how it works inside. It is the contract that says what you can ask for, how to ask, and what you get back.
What an API actually is
An API is a contract between two programs. One side offers capabilities (read a user, charge a card, send a message) and publishes the exact way to invoke them. The other side calls those capabilities without ever seeing the source code or the database behind them.
Think of a power socket. You do not need to understand the grid to plug in a laptop. The socket is the interface: a fixed shape, a fixed voltage, a guaranteed behavior. An API is that socket for software. As long as both sides honor the shape, the backend can be rewritten from scratch and the caller never notices.
The contract has three parts: the endpoints or methods you can call, the shape of the input you send, and the shape of the output you get back, including errors. A well-defined API treats this contract as a promise. Break it and every client that depends on you breaks too.
How a request flows under the hood
Most APIs people build today are HTTP APIs. A client sends an HTTP request to a URL like GET /users/42. That request carries a method (GET, POST, PUT, DELETE), headers (auth tokens, content type), and often a JSON body. The server routes it to the right handler, runs the logic, talks to a database, and returns a status code plus a JSON response.
Status codes are part of the contract, not decoration. 200 means success, 201 means created, 400 means the client sent bad input, 401 means not authenticated, 404 means not found, 500 means the server broke. A client reads the code first and the body second.
REST is the dominant style: resources have URLs and standard verbs act on them. GraphQL is an alternative where the client asks for exactly the fields it wants in one query. gRPC uses binary Protocol Buffers over HTTP/2 for fast service-to-service calls. All three are APIs; they just differ in shape and tradeoffs.
When to use one, and the tradeoffs
You reach for an API any time two systems must talk across a boundary: a browser to a backend, one microservice to another, your app to Stripe or Twilio. The API hides complexity and lets each side change independently as long as the contract holds.
The main tradeoff is versioning. Once other teams or customers depend on your API, you cannot freely change it. Removing a field or renaming an endpoint is a breaking change, so teams version their APIs (/v1/, /v2/) and deprecate old versions on a schedule rather than yanking them.
Other real costs are latency (every API call is a network round trip, often 10 to 200 ms), security (every public endpoint is an attack surface that needs auth and rate limiting), and over-fetching. REST can force a client to make several calls or download fields it does not need, which is exactly the pain GraphQL was built to solve.
A concrete example
Say your app needs to charge a customer. You do not build a payment processor; you call Stripe's API. You send POST /v1/charges with an amount, a currency, and a card token, plus your secret key in the Authorization header. Stripe runs fraud checks, talks to the card networks, and replies with a JSON object describing the charge and a 200 status, or a 402 if the card is declined.
Your code never sees Stripe's database or fraud models. You only see the contract. When Stripe rewrites its internals, your integration keeps working because the request and response shapes stay the same. That is the whole point of an API: a stable surface over a system you do not control and do not need to understand.
Where it is used in production
Stripe
Exposes a REST API for payments, refunds, and subscriptions so apps can charge cards without handling card data or PCI compliance themselves.
Twilio
Offers HTTP APIs to send SMS, make calls, and run WhatsApp messaging; you POST a message body and Twilio handles the carrier networks.
GitHub
Publishes both a REST API and a GraphQL API so tools and CI systems can read repos, open issues, and trigger workflows programmatically.
Google Maps Platform
Provides geocoding, directions, and places APIs that millions of apps call to turn an address into coordinates or draw a route.
Frequently asked questions
- What is the difference between an API and a library?
- A library is code you import and run inside your own process. An API is usually a remote contract you call over a network or process boundary, so the actual work happens on someone else's machine. The word API also covers the public surface of a library, but in web work it almost always means an HTTP endpoint.
- What is the difference between REST and GraphQL?
- REST exposes many fixed endpoints, each returning a set response, so you may need several calls or get fields you do not need. GraphQL exposes one endpoint where the client writes a query asking for exactly the fields it wants in a single request. REST is simpler to cache and reason about; GraphQL avoids over-fetching but is harder to cache.
- How do APIs stay secure?
- Public APIs require an API key or a token (often OAuth or a JWT) in the request headers, sent over HTTPS so it cannot be read in transit. Servers then apply rate limiting to stop abuse, validate every input to block injection, and check that the caller is allowed to touch the specific resource before responding.
- What does it mean to version an API?
- Versioning means publishing a numbered contract, like /v1/, so existing clients keep working while you build /v2/ with breaking changes. You announce a deprecation date for the old version instead of changing it underneath callers. This lets your backend evolve without breaking every app that depends on you.
- What is an API endpoint?
- An endpoint is a single callable address in an API, such as GET /users/42 or POST /charges. It pairs a URL path with an HTTP method and represents one specific operation. The full set of an API's endpoints, inputs, and outputs makes up the contract.
Learn API hands-on
This page explains the idea. The full lesson lets you step through the ring as servers join and leave, read the implementation, and check yourself with a quiz. It is one of 760+ lessons in the System Design Masterclass, from your first API call to distributed consensus. Eleven Foundation lessons are free, no signup. Lifetime access is ₹499 in India or $7.99 worldwide, one payment, no subscription.
Related lessons
Lessons that touch on API as part of a larger topic.
API Documentation (Swagger/OpenAPI)
How API specification standards like OpenAPI let teams build, test, and consume APIs without guessing
foundation · core fundamentals
API Keys
The simplest way to identify and authenticate API consumers, a shared secret with limits
intermediate · api design protocols
API Versioning
Evolve your API without breaking existing consumers, strategies for managing change
intermediate · api design protocols
API Rate Limiting
Putting it all together, designing rate limiting for production APIs at scale
intermediate · api design protocols
API Composition
Aggregate data from multiple microservices into a single response at the API layer
intermediate · api design protocols
See also
Related glossary terms you might want to look up next.
REST API
An architectural style for building APIs using standard HTTP methods (GET, POST, PUT, DELETE). Resources are identified by URLs.
GraphQL
A query language for APIs where the client specifies exactly what data it needs. No over-fetching, no under-fetching. One endpoint to rule them all.
gRPC
A high-performance RPC framework by Google using Protocol Buffers and HTTP/2. Much faster than REST for service-to-service communication.
Latency
The time delay between sending a request and getting a response. Amazon found every 100ms of extra latency costs 1% in sales.
Throughput
The number of operations a system can handle per unit of time. Think of it as how many cars a highway can move per hour.
Bandwidth
The maximum amount of data that can be transferred over a network in a given time. It's the width of the pipe, not how fast the water flows.