Almost every system you design is made of pieces of software that need to talk to each other. APIs are how they do it.

This lesson covers what an API actually is, how API requests and responses work, and why APIs are such an important building block in system design.

An API, or Application Programming Interface, defines how one piece of software can communicate with another.

You use APIs all the time, even if you never see them.

When you open a food delivery app, the app might call one API to fetch nearby restaurants, another to place your order, another to process the payment, and another to track the delivery.

The mobile app doesn't need to know how any of those systems work internally. It only needs to know how to communicate with them.

That's the basic idea behind an API.

At a high level, an API is a contract that defines how two pieces of software communicate with each other.

It tells the client:

For example, imagine a mobile app that needs information about a user. The app might send a request like this:

And the server might return a JSON object with an id of 123 and a name of Alice:

The mobile app doesn't need to know how the server finds that user. The data might come from a database, a cache, or even another service.

All the client needs to understand is the API contract: send this request, and expect a response in this format.

Most APIs involve two sides: a client and a server.

The client is the application that sends a request. This could be a web app, a mobile app, a command-line tool, or even another backend service.

The server receives that request, performs some work, and sends back a response.

For an HTTP API, a request usually has a few important parts.

Suppose we want to create a new order. The request might look like this:

It includes an Authorization header containing a bearer token, a Content-Type header set to application/json, and a JSON body for restaurant 42, with item 101 and a quantity of two.

HTTP Method

The first part is the HTTP method. Here, POST tells the server that we want to create something or perform an action.

Endpoint

Next is the endpoint, in this case /orders, which identifies the resource or operation we want to access.

Headers

Then we have headers. Headers carry additional information about the request, such as:

Query Parameters

A request can also include query parameters. These are values added to the URL to provide extra input:

Here, category and limit narrow down which products come back.

Request Body

And finally, methods like POST, PUT, and PATCH often include a request body, which contains the actual data we want to send to the server. In the order request above, the body is the JSON object with the restaurant and the items.

So at a high level, an HTTP API request can include five main pieces:

Not every request uses all of them, but these are the core building blocks you'll see again and again.

An API endpoint is a specific URL that a client can call to interact with a resource or perform an operation.

For example, a user service might expose endpoints like these:

The path usually identifies the resource, while the HTTP method tells the server what action the client wants to perform. Three of these endpoints share the same path, /users/123. The method is what makes them different operations.

You can think of endpoints as the entry points into a service. A single backend might expose dozens or even hundreds of endpoints, each representing a different capability that clients can use.

Once the server processes a request, it sends back an API response.

A response usually contains three main parts: a status code, headers, and optionally a response body.

For example, if a request succeeds, the server might return 200 OK, with a Content-Type header set to application/json, and a JSON object with an id of 123 and a name of Alice:

Status Code

The status code tells the client what happened. Here are some common ones:

Codes in the 2xx range mean the request worked. Codes in the 4xx range mean the client sent something the server could not accept, and codes in the 5xx range mean the server failed.

Headers

The headers provide additional metadata about the response, such as the content type (Content-Type) or caching information (Cache-Control).

Response Body

And the response body contains the actual data being returned. It is optional: a successful DELETE, for example, may return a status code with no body at all.

One of the most important benefits of an API is that it hides the internal implementation of a system.

Imagine a client calls:

From the client's point of view, that is just one API request. But behind that endpoint, the server might check a cache, query a database, call another service, or even run a machine learning model before returning the result.

The client does not need to know any of that. It only needs to know the API contract: what request to send and what response to expect.

This creates a clean boundary between the client and the server. The backend team can change the database, add caching, split one service into several services, or completely rewrite the internal logic without affecting the client, as long as the API contract stays the same.

That separation reduces coupling and makes different parts of a system easier to evolve independently.

APIs can be grouped based on who is allowed to use them.

Public APIs

A public API is exposed to external developers. For example, a payment company might provide an API that lets other businesses accept payments, or a maps provider might expose an API for location and routing data.

Because people outside the company depend on a public API, it needs clear documentation, authentication, rate limits, and a careful plan for changing behavior without breaking callers.

Private APIs

A private API, sometimes called an internal API, is used only inside an organization. For example, an Order Service might call an internal Inventory Service API to check whether a product is available.

Internal does not mean informal. Internal APIs still need owners, timeouts, stable request and response shapes, and clear behavior when something fails.

Partner APIs

Then there are partner APIs, which are exposed only to selected external companies or business partners.

So the main difference is not how the API works technically, but who is allowed to access it.

In large systems, most APIs are often internal, because services constantly need to communicate with other services behind the scenes.

A good API should be easy to understand, predictable, and difficult to misuse.

We'll cover many of these topics later in the course, but the main idea is that a good API is not just functional. It should provide a clear and reliable contract that clients can safely depend on.

In the next lesson, we'll look at the different types of APIs you're likely to encounter in real-world applications and when each one is used.