What an API Is
A phone app shows a list of library books. The phone does not hold the library's catalogue, and it has no business reaching into the library's database. Instead it sends a short, well-formed request to the library's server and gets back exactly the data it asked for. The agreement that makes that exchange possible is an API.
The rule
An API is a published promise: send this, and you will get that.
API stands for Application Programming Interface. It is the part of a program that other programs are allowed to use. Three ideas sit inside the rule:
- Published: the rules are written down, so a stranger can use the API without reading its source code.
- Promise: the provider commits to keeping it working. Callers build on it, so breaking it breaks them.
- Send this, get that: every interaction is a request with a known shape and a response with a known shape.
Throughout this course we design one API: BookNook, a small library service at https://api.booknook.example/v1. It manages books, members and loans. Here is one exchange:
GET /v1/books/42 HTTP/1.1
Host: api.booknook.example
HTTP/1.1 200 OK
Content-Type: application/json
{"id": 42, "title": "The Hobbit", "available": true}The caller never sees which database, language or server BookNook uses. That hidden part can change freely, as long as the promise holds. This separation is the whole point: the interface stays still while the implementation moves.
APIs are everywhere, not only on the web. A programming language's standard library is an API; so is the set of calls an operating system offers. In this course "API" mostly means a web API: a service that programs reach over the network, usually with HTTP.
The shortcut
To understand any API fast, find its four parts: who calls, what they send, what comes back, what is promised.
Who calls?
The BookNook phone app, acting for a signed-in member.
The common trap is thinking of an API as "the server" or "the database". It is neither. It is the contract between them and the outside world.
Drills
Answer fast — trust the rule.
Which best describes an API?
BookNook moves from one database engine to another, and every request and response stays identical. What happens to callers?
Which change to BookNook would break its promise to existing callers?
Which of these is also an API, even though it has no network?
Remember
- An API is a published promise: send this request shape, get that response shape.
- Shortcut: who calls, what they send, what comes back, what is promised.
- Trap: the API is the contract, not the server or database behind it.