What Is an API? A Simple Explanation

TL;DR

• An API (Application Programming Interface) is a set of rules that lets one piece of software ask another for data or for an action [1][2].
• Think of a waiter: you do not walk into the kitchen, you place an order and the waiter brings back what you asked for.
• On the web, an app sends a request and a server sends back a response, usually with a status code and some data.
• You use APIs all the time without seeing them, for example when a weather app shows a forecast.

The restaurant analogy #

Imagine you are in a restaurant. You are the app, the kitchen is the server that holds the food, or in software terms the data and functions. You do not go into the kitchen and cook. You tell the waiter what you want from a menu, and the waiter carries your order to the kitchen and brings the meal back.

The waiter is the API. The menu is its documentation: it lists what you may ask for and how to ask. If you order something that is not on the menu, the waiter says no. MDN describes an API as a simple contract between the application that offers it and other software that wants to use it [1].

The same idea appears with a weather app. It does not measure the weather itself. It calls the API of a weather service, which looks up the forecast and returns it for the app to display [2].

What a request and response look like #

On the web, APIs usually run over HTTP, the same protocol browsers use. The client always starts the conversation with a request, and the server answers with a response [3].

A request contains:

• a method, such as GET to fetch something or POST to send something
• a path that says which resource you want
• optional headers with extra details, and an optional body [3]

A response contains a status code that says whether it worked (for example 200 for success), headers, and often a body with the data [3].

A simple example, shown in plain words:

The data is often sent in a format called JSON, which is easy for programs to read. Code that calls an API should also check the outcome. MDN notes, for instance, that a browser fetch does not treat a 404 error as a failed request, so a developer has to check the response status themselves [4].

Common types of API #

APIs are grouped in a few ways [2]:

• By style. REST is the most popular on the web. It uses HTTP and standard operations such as GET and DELETE. Others include SOAP, RPC and WebSocket, which allows two-way messages.
• By who may use them. Private APIs are internal to one company. Public APIs are open to anyone, sometimes with a key or a cost. Partner APIs are limited to approved outside developers.

Not every API is on the internet. A browser also offers APIs to code running in a page, such as one that reads your location when you give permission [1].

Why APIs matter #

• Reuse. A developer can add maps, payments or sign-in without building them from scratch.
• Hidden complexity. The caller needs to know the menu, not how the kitchen works.
• Control. The owner decides what can be asked for and can require authorization.

Because an API is a doorway into a system, it needs the same care as any other. Services often ask callers to authenticate, and good ones send data over HTTPS so it cannot be read in transit.

FAQ #

Is an API the same as a website? #

No. A website is designed for people to read. An API is designed for programs to use, so it returns structured data rather than a styled page.

What is a REST API? #

It is a common way of building web APIs. A client sends HTTP requests, and the server returns data. REST servers are described as stateless, which means they do not remember a client between requests [2].

Do I need to code to use an API? #

To build with one, usually yes. But you benefit from APIs every day through the apps that use them, and some tools let non-programmers connect services without writing code.

What is an API key? #

It is a code that identifies the app or developer calling an API, so the provider can control access and usage. Treat it like a password and do not publish it.

Sources #