We use analytics cookies.We use cookies to analyze site traffic and improve your experience.
Loading...
System Design and AI Engineering, by Roni Das. 984 interactive lessons.
Start LearningFoundation · Core Fundamentals
Application Programming Interface: a contract defining how two pieces of software talk to each other. The waiter between your frontend and your backend.
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.
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.
Learn it in the course
This page is the free part.
₹1,111 in India$25 everywhere elseonce, for the whole course
The System Design course covers API across a run of lessons, not one page. These 4 alone are about 75 minutes of step-by-step reading, 1 of them with code you run in the browser, all with a quiz.
Standard web service architecture using HTTP methods and resource-based URLs.
How API specification standards like OpenAPI let teams build, test, and consume APIs without guessing.
The simplest way to identify and authenticate API consumers, a shared secret with limits.
Evolve your API without breaking existing consumers, strategies for managing change.
all part of
System Design Masterclass
770 lessons · about 287 hours · 18 free to read
₹1,111in India, by UPI
$25everywhere else, by PayPal
It is really nice and good Please join the course
You own this course
Continue with REST APIpay once,
yours for life
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
API Documentation (Swagger/OpenAPI)
How API specification standards like OpenAPI let teams build, test, and consume APIs without guessing
API Keys
The simplest way to identify and authenticate API consumers, a shared secret with limits
API Versioning
Evolve your API without breaking existing consumers, strategies for managing change
API Rate Limiting
Putting it all together, designing rate limiting for production APIs at scale
API Composition
Aggregate data from multiple microservices into a single response at the API layer
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.
This page explains the idea. The "REST API" lesson builds it up step by step, with diagrams. It is part of the System Design Masterclass course, which has 770 lessons. 18 of them are free to read. You pay once and keep it for life, with no subscription.
Open the REST API lessoncourse 1
From absolute beginner to principal engineer, drawn step by step.
Asked about API in an interview?
Each question has why it is asked, a full answer, what the interviewer listens for, the follow-ups, the common mistakes and a diagram (268 diagrams in all). A PDF you keep, junior to staff level.
India: UPI, cards or netbanking through Razorpay. Elsewhere: card or PayPal. Download at once from My packs.
