Programming · concepts · web
What is an API?
You hear it constantly: "call the API", "the public API", "an API key". An API (Application Programming Interface) is one of the most useful ideas in software — and one of the most over-jargonized. This guide explains, plainly, what an API is, the main kinds you will meet, how a typical web API request works, and why APIs are everywhere.
The short definition
An API is a contract that lets one piece of software talk to another. It defines what requests you can make, what data you must send, and what you get back — without you needing to know how the other side is built internally.
The classic analogy is a restaurant. You (one program) read a menu (the API) and place an order with the waiter. You do not walk into the kitchen or need to know how the dish is cooked. The menu is the agreed interface; the kitchen is the implementation, hidden behind it. An API is that menu for software.
The main kinds of API
- Web APIs (the most talked-about) — one program talks to another over the network, usually over HTTP. When a weather app shows the forecast, it calls a weather service's web API. Most modern web APIs follow the REST style and exchange data as JSON.
- Library / framework APIs — the set of functions and types a code library exposes for you to call. When you use a date library, the functions it gives you are its API.
- Operating-system APIs — how a program asks the OS to open a file, draw a window, or use the network. POSIX is one such API.
The common thread: an API is the published surface of something, the part you are allowed to use, separated from the internals you are not supposed to depend on.
How a web API request works
A web API call is a request and a response. The client sends an HTTP request to a URL (an endpoint) using a method that signals intent, and the server sends back a status code and usually some data. The common methods:
- GET — read data ("give me user 42").
- POST — create something new.
- PUT / PATCH — update something.
- DELETE — remove something.
A simple request to read a user might look like this, with the server replying in JSON:
GET /users/42 HTTP/1.1
Host: api.example.com
-- response --
200 OK
{ "id": 42, "name": "Ada", "active": true }The 200 is a status code meaning success; 404 means not found, 401 not authenticated, 500 a server error. The body is JSON — the lightweight, human-readable format most web APIs use to exchange structured data.
Authentication and keys
Many APIs require you to identify yourself with an API key or a token, sent in a request header. This lets the provider control who uses the service, apply rate limits, and bill usage. Keep keys secret — a leaked key is like a leaked password.
Why APIs matter
APIs are what let software be composed rather than rebuilt. A shop can take payments without writing a bank; an app can show a map without drawing the world; services inside one company talk to each other through internal APIs. They turn other people's capabilities into building blocks you can call in a few lines — which is most of how modern software gets built.
The honest limits
An API is a dependency. If the provider changes it, rate-limits you, raises prices or shuts down, your software is affected — which is why good APIs are versioned and documented, and why you handle errors and timeouts rather than assuming every call succeeds. An API hides complexity; it does not remove it.
The bottom line
An API is a contract that lets one program use another's capabilities through a defined set of requests and responses, without touching its internals. Web/REST APIs over HTTP with JSON are the kind you will meet most, but the idea — a published interface separated from the implementation behind it — runs through libraries, operating systems and every well-structured program. Learn to read an API's documentation and you can plug almost anything into anything.
New to a language to build or call APIs from? Browse our guides index for clear, original programming explainers.