What Is an API?

A delivery application shows that a package will arrive before six in the evening.

The application holds no delivery data of its own. It asked another program for the answer: it sent a short message naming one tracking number, and a server operated by the carrier sent back a small structured reply. The application then arranged those values on the screen.

The agreement that made that exchange possible is an API.

An API, short for application programming interface, is a published agreement that lets one program use another program's capability without knowing how that capability is built.

Two words in that sentence carry most of the meaning. Published means somebody outside the implementation is relying on it. Interface means the agreement is the visible surface, and the machinery behind it is deliberately hidden.

1. The Two Sides of Every API

Every API has a provider and a consumer.

The provider is the team or service that publishes the API and operates the code behind it. The consumer, also called the caller or the client, is the program that uses it. In the delivery example, the carrier is the provider and the phone application is the consumer.

The two sides are usually different programs, often written in different languages, frequently owned by different teams, and sometimes owned by different companies. That separation is the point. The consumer needs the carrier's tracking capability without joining the carrier's engineering team.

2. What One Call Contains

A call has two halves. The consumer sends a request, and the provider returns a response.

A request to read one shipment looks like this:

GET /shipments/shp_81M
Authorization: Bearer <credential>

The response carries the answer:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "shp_81M",
  "tracking_number": "1Z-4471-9930",
  "status": "in_transit",
  "estimated_delivery_at": "<RFC 3339 UTC timestamp>"
}

Every part of that exchange has a name, and the rest of the course uses those names constantly.

An operation is one named thing a caller can do, such as reading one shipment. The method says what kind of interaction the caller wants. The path identifies which thing the caller is addressing. Headers carry information about the request rather than the thing itself, such as the credential proving who is calling. The body, also called the payload, is the structured data the message carries. The status code is a short number telling the caller how the attempt ended.

The contract is all of that together, plus the promises no single message shows: which fields are always present, what happens when the shipment does not exist, whether repeating the call is safe, and how much of this will still be true a year from now.

3. The Vocabulary in One Place

These terms recur in every chapter, so it is worth reading them once as a set.

Two of them are easy to confuse. An endpoint is a location the caller can address. An operation is one thing the caller can do at that location. Reading a shipment and deleting a shipment can share one address while remaining two operations with different inputs, different permissions, and different failures.

4. Why Programs Publish an API at All

Building the capability again is always an option. An API is worth its cost when at least one of these applies.

Reuse without rebuilding. The phone application does not operate a delivery network. One published call replaces work the consumer could never do on its own.

The implementation stays replaceable. The carrier can move from one database to another, split a service in two, or add a cache, and the consumer keeps sending the same request. This is the benefit the whole course protects, and it survives only while the contract stays stable.

Access stays controlled. The provider decides who may call, what each caller may see, and how often. A published surface is easier to secure than direct access to storage.

Teams move independently. Inside one company, an API is the line that lets two teams release on their own schedules instead of coordinating every change.

Other people build things you did not plan. A payment API becomes part of products its authors never designed. That is the largest benefit and also the reason published decisions become so difficult to reverse, which Section 6 covers.

5. The Kinds of API You Will Meet

The word covers several different things, and interviews mix them freely.

By where the code runs. A library API is the set of functions one program exposes to code running in the same process. An operating-system API is how a program asks the machine to open a file or a network connection. A web API is reached over a network, and it is what an API design interview almost always means.

By who is allowed to call. This distinction changes the contract more than any other, so the course returns to it repeatedly.

By the style of the contract. A web API can be expressed in more than one way. REST addresses things by URL and acts on them through a small fixed set of methods. gRPC defines typed service methods in a schema and generates code for both sides. GraphQL publishes a typed graph and lets the caller select the fields it wants. Related mechanisms cover what a plain request cannot: webhooks, where the provider calls the consumer back, and streaming, where one connection carries a sequence of updates.

The course uses REST as its default because it is the most common interview vocabulary, and Chapter 2 designs it in full. Chapter 3 covers the rest, including the trigger that justifies each one and the cost it brings.

6. Published Decisions Are Permanent Decisions

This is the central idea of the course, and it is the reason API design is a distinct skill rather than a naming exercise.

Imagine that you own an internal function:

loadCustomerProfile(customerId)

You decide getCustomerProfile is clearer. Tools find the call sites, you update them, and you deploy. You control both the function and its callers.

Now imagine your API publishes this response:

{
  "user_id": "usr_7241",
  "display_name": "Mina Patel"
}

Six months later you decide name is cleaner than display_name. If you rename it, existing applications still look for the old field. They may show a blank label, reject the response, or fail somewhere you cannot see. Some callers are partner integrations at other companies, some are scripts with no maintainer, some are old mobile applications nobody has updated. No tool finds those callers for you, and you cannot make them all deploy at the same time as you.

The small rename is now a compatibility project, and the diagram below shows what it costs.