APIs Explained: How Software Talks to Software
What an API actually is, how a request and response work, and why almost every app you use depends on them.
Every time you check the weather in an app, pay online, or log in with a Google account, at least one API is doing the work behind the scenes. The idea is simpler than the acronym suggests.
The restaurant analogy
You do not walk into a restaurant kitchen and cook. You tell the waiter what you want, the kitchen prepares it, and the waiter brings it back. You never see the kitchen.
An API — an application programming interface — is the waiter. It is a defined way to ask another system for something, without knowing or touching how that system works internally.
Request and response
Most modern APIs are web APIs, and they follow the same pattern as browsing a website:
- Your program sends a request to a URL.
- The server processes it and sends back a response.
- The response contains a status code, headers and usually a body.
A typical request looks like this:
GET https://api.example.com/books/42
Authorization: Bearer YOUR_TOKENAnd the response:
{ "id": 42, "title": "Deep Work", "author": "Cal Newport" }The verbs
HTTP APIs use a small set of methods, and each carries a meaning:
| Method | Meaning | Example |
|---|---|---|
| GET | Read something | Fetch a list of books |
| POST | Create something | Add a new book |
| PUT / PATCH | Update something | Change a title |
| DELETE | Remove something | Delete a book |
Keeping to these meanings makes an API predictable, which is the entire point.
Status codes
The three-digit code tells you what happened before you read the body:
- 2xx — success.
200 OK,201 Created. - 4xx — your request was wrong.
401unauthorised,403forbidden,404not found,429rate limited. - 5xx — the server failed.
500internal error.
When debugging, the status code is the first thing to read.
Authentication
Most APIs need to know who is asking. The common approaches:
- API keys — a simple secret string. Easy, but hard to scope and easy to leak.
- Tokens (OAuth) — the standard for letting a user grant limited access without sharing a password. This is what "log in with Google" uses.
Rules that matter: never put keys in front-end code or public repositories, and treat a key like a password.
Rate limits and pagination
Two constraints you will meet immediately:
- Rate limits cap how many requests you may make per minute or day. Exceeding them returns
429. Respect the limit and back off. - Pagination splits large results into pages. Expect parameters like
?page=2or?limit=100&offset=200.
Practical advice
- Read the documentation first. Half of all API frustration is guessing parameter names.
- Test with a simple tool before writing code — send one request and inspect the raw response.
- Handle failure properly. Networks drop and APIs go down. Retry briefly, then fail gracefully.
- Cache what rarely changes. It reduces cost and avoids hitting limits.
- Do not assume the shape of the data. Fields get renamed and added.
The bottom line
An API is a contract: a defined way to ask for data or actions, with defined answers. Once you see requests, responses, verbs and status codes as one pattern, the rest is documentation.
