System Design

What Is an API? A Beginner's Guide That Goes Deep

APIs are how software talks to software - the invisible contracts behind every app, website, and system you use. This guide takes you from the restaurant analogy all the way to what an interviewer expects you to know.

By Admin2026-06-1813 min readapiresthttpbackendsystem-designfundamentals

Every app on your phone is quietly talking to other software all the time. When you check the weather, your weather app isn't computing the forecast itself - it's asking a weather service. When you log in with Google, one app is asking Google to confirm who you are. When you pay with a card online, the store is asking a payment service to handle the money. All of these conversations happen through APIs.

API stands for Application Programming Interface. That name is intimidating and not very helpful, so let's start with what it actually means in plain language, build up to how APIs really work, and finish with the parts an interviewer will expect you to understand. By the end, "API" should feel obvious rather than mysterious.

The simplest definition

An API is a contract that lets one piece of software talk to another. It defines what requests you can make and what responses you'll get back - without you needing to know how the other software works inside.

That last part is the key. An API hides the complexity. You don't need to understand how the weather service collects data from satellites and runs forecasting models. You just need to know: "if I ask this service for the weather in Mumbai, it will give me back the temperature." The API is the agreed-upon way to ask and the agreed-upon shape of the answer.

The restaurant analogy

The classic way to understand this: think of a restaurant.

You sit at a table and you want food. You don't walk into the kitchen, find the ingredients, and cook it yourself. Instead, there's a menu that tells you what you can order, and a waiter who takes your order to the kitchen and brings back your food.

In this analogy:

• You are the application making a request (the "client").
• The kitchen is the system that does the actual work (the "server").
• The menu is the API - it tells you exactly what you're allowed to ask for.
• The waiter carries your request to the kitchen and the result back to you.

You don't need to know how the kitchen works. You just need to know what's on the menu and how to order from it. The API is that menu plus the waiter - a defined set of things you can ask for, and a reliable way to ask. This is why APIs are so powerful: they let software use other software without understanding its internals.

sequenceDiagram
    participant C as Client (your app)
    participant A as API
    participant S as Server (the system)
    C->>A: Request: "Give me the weather in Mumbai"
    A->>S: forwards the request
    S->>S: does the work (looks up the forecast)
    S->>A: returns the result
    A->>C: Response: "32°C, sunny"

This sequence diagram shows how an API call works. A client app sends a request to an API asking for the weather in Mumbai. The API forwards the request to the server, which does the work of looking up the forecast. The server returns the result to the API, which passes the response - 32 degrees and sunny - back to the client.

Why APIs exist

APIs solve several fundamental problems at once, which is why they're everywhere:

• Abstraction. They hide complexity. You use a service through a simple interface without understanding its internals - exactly like ordering from a menu instead of cooking.
• Reuse. One service can be used by many different applications. A single payment API serves thousands of online stores; none of them had to build payment processing themselves.
• Separation of concerns. Teams can work independently. The team building the weather service and the team building a weather app only need to agree on the API contract - then each can change their own internals freely.
• Security and control. An API is a controlled doorway. The provider decides exactly what you can and can't do, what data you can see, and how often you can ask - rather than giving you direct access to their system.

How a web API actually works

Most APIs you'll encounter are web APIs - they work over the internet using HTTP, the same protocol your browser uses to load web pages. A web API conversation has two halves: a request and a response.

The request

When a client calls an API, it sends a request with several parts:

• The endpoint (URL). Where you're sending the request - the address of the specific resource you want. For example, https://api.weather.com/forecast/mumbai.
• The method. What you want to do. HTTP defines a small set of methods (more on these below).
• Headers. Extra information about the request - who you are (authentication), what format you want the response in, and so on.
• The body (optional). The data you're sending, used when you're creating or updating something. Usually formatted as JSON.

HTTP methods

The method tells the server what kind of operation you want. The main ones:

A useful mental model: GET reads, POST creates, PUT/PATCH update, DELETE removes. GET is safe (it changes nothing) and GET, PUT, and DELETE are idempotent - doing them repeatedly has the same effect as doing them once, which matters a great deal in distributed systems.

The response

The server sends back a response with two main parts:

• A status code. A three-digit number summarizing what happened.
• The body. The actual data you asked for (or an error message), usually in JSON.

Status codes

Status codes are grouped by their first digit, and knowing the families is enough to read almost any response:

The 4xx versus 5xx distinction matters: 4xx means your request was wrong (bad data, missing authentication, asking for something that doesn't exist), while 5xx means the server broke while handling a valid request. That difference tells you whether to fix your request or whether the problem is on their end.

A worked example

Say you want a user's profile. The request and response might look like this:

GET /users/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer abc123
Accept: application/json

And the server responds:

{
  "id": 42,
  "name": "Priya Patel",
  "email": "priya@example.com",
  "joined": "2024-03-15"
}

That's a complete API interaction: you asked (GET) for a specific resource (/users/42), proved who you were (the Authorization header), and got back a 200 OK with the data as JSON. Nearly every web API call you'll ever make follows this same shape.

Tip: JSON (JavaScript Object Notation) is the most common format for API data because it's human-readable and works in every programming language. It represents data as key-value pairs and lists - like the user object above. You'll see it constantly, so getting comfortable reading it pays off quickly.

Common API concepts you'll meet

As you go deeper, a handful of concepts come up repeatedly:

• Authentication. Proving who you are, usually with an API key or a token sent in the headers. Without it, the API doesn't know whether to trust you or what data you're allowed to see.
• Rate limiting. APIs cap how many requests you can make in a time window, to protect themselves from overload and abuse. Exceed the limit and you'll get a 429 Too Many Requests response.
• Pagination. When a request would return thousands of results, APIs return them in "pages" - a chunk at a time - so responses stay fast and manageable. You request the next page as needed.
• Versioning. APIs change over time, but existing clients depend on the old behavior. Providers handle this by versioning - for example api.example.com/v1/ and api.example.com/v2/ - so they can introduce changes without breaking everyone.
• Endpoints and resources. A well-designed API is organized around resources (users, orders, products), each with its own endpoint. GET /users lists users; GET /users/42 gets one; POST /users creates one. This consistent structure is a hallmark of REST, the most common API style.

Types of APIs

Not all APIs are web APIs. The term applies broadly:

• Web APIs talk over the internet via HTTP - the focus of this guide and what most people mean by "API" today. Styles include REST, GraphQL, and gRPC.
• Library APIs are the functions a code library exposes for you to call. When you use a charting library and call its drawChart() function, that function is part of the library's API.
• Operating system APIs let applications request services from the OS - reading a file, opening a network connection, drawing on the screen.

The common thread across all of them is the same definition we started with: a defined interface that lets one piece of software use another without knowing its internals.

It's also worth distinguishing an API from an SDK (Software Development Kit). An API is the interface; an SDK is a toolkit - often including a convenient wrapper around an API - that makes building with it easier. You call an API; you build with an SDK.

Why APIs matter in system design interviews

This isn't just background knowledge - APIs are central to system design interviews. When you're asked to design a system, defining the API is one of the core early steps. After you clarify requirements, you typically sketch the key endpoints: what operations the system supports, what each one takes in, and what it returns.

A clear API forces precision. It pins down exactly what your system does and gives you and the interviewer a shared vocabulary for the rest of the discussion. Candidates who can quickly lay out a clean set of endpoints - POST /tweet, GET /timeline, POST /follow - demonstrate that they think in terms of contracts and interfaces, which is exactly the structured thinking interviewers reward.

Interview: In a system design interview, after clarifying what the system should do, propose the API early: a handful of endpoints with their methods, inputs, and outputs. It shows you can translate vague requirements into a concrete interface - and it anchors the entire rest of the conversation. Vague designs that skip this step are much harder to evaluate and much easier to get lost in.

A real-world walkthrough: opening a weather app

Let's trace a single, familiar action all the way through to make this concrete. You open a weather app and it shows the forecast for your city. Here's the chain of API calls happening in the half-second before the screen fills in:

First, the app needs to know where you are. It calls your phone's operating system API to get your GPS coordinates - software (the app) asking other software (the OS) for a service, through a defined interface. The OS returns something like latitude 19.2, longitude 73.2.

Next, the app calls a weather web API over the internet: GET /forecast?lat=19.2&lon=73.2, with an API key in the headers to prove the app is authorized to use the service. This request travels to the weather company's servers, which look up the forecast for those coordinates and return a 200 OK with a JSON body containing temperature, conditions, and an hourly breakdown.

The app then takes that JSON, reads the fields it cares about, and renders them on screen - perhaps calling a library API from a charting library to draw the temperature graph. Three different kinds of API (operating system, web, and library), three different pieces of software cooperating, all through clean contracts - and you experienced it as simply "the weather appeared." That seamlessness is exactly what APIs are for: they let independently-built software cooperate without any of them understanding the others' internals.

What makes a good API

Not all APIs are created equal. The qualities that separate a well-designed API from a frustrating one are worth knowing, because they show up both when you use APIs and when an interview asks you to design one:

• Consistency. Similar operations should look similar. If GET /users/42 gets a user, then GET /orders/99 should get an order - the same predictable pattern. Surprises are the enemy of a good API.
• Clear, meaningful responses. Successful requests return useful data; failed ones return helpful error messages and the right status code, so the caller knows what went wrong and how to fix it.
• Good documentation. An API is only as usable as its documentation. The best APIs explain every endpoint, every parameter, and show example requests and responses.
• Stability. Once other software depends on your API, changing it breaks them. Good APIs evolve carefully - adding new capabilities without breaking existing callers, and versioning when a breaking change is unavoidable.
• Sensible security. A good API authenticates callers, authorizes what each can access, and rate-limits to protect itself - all without making legitimate use painful.

Tip: When you use a well-designed API, it feels almost invisible - you ask for what you want and get it, with no surprises. That invisibility is the goal, and the principles above are what create it. They're also exactly what an interviewer is checking for when they ask you to design one.

Where to go next

APIs are the doorway to nearly every other system design topic. Once you understand that systems talk to each other through defined contracts, you're ready to ask the deeper questions: Which style of API should you use - REST or GraphQL? How do you protect an API with rate limiting? How do you keep an API reliable when the services behind it fail? Each of those is a topic of its own.

The fundamentals here - request and response, methods and status codes, endpoints and resources - are the bedrock. Everything else in backend and system design builds on this foundation. We start exactly here and build all the way up across System Design Fundamentals.

Go deeper

• API (Wikipedia) - the formal definition and the history of the concept.
• HTTP request methods (MDN) - the canonical reference for GET, POST, PUT, DELETE, and the rest.
• HTTP response status codes (MDN) - every status code and what it means.
• REST API design - the principles behind the most common web API style.

More articles