What Is an API? – Definition and How It Works
Learn what an API is, how a web API request and response are structured, what a contract guarantees, and the styles you will meet in practice.
An application programming interface is an agreed way for one program to use another. On the web it usually means an HTTP endpoint that accepts a structured request and returns structured data.
1. What Is an API?
An API is a contract: a defined set of operations, their inputs, and their outputs.
- Key idea: the caller depends on the contract, not on how the service is built.
- Mechanism: requests carry a method, a path, headers, and often a body; responses carry a status, headers, and a body.
- Goal: let systems interoperate without sharing code or internals.
Example of a Web API Call
POST /api/v1/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer <token>
{"query": "web scraping", "limit": 10}
2. The Parts of a Request
| Part | Carries |
|---|---|
| Method | The intent — retrieve, create, replace, delete |
| Path | Which resource or operation |
| Query string | Filters, pagination, options |
| Headers | Authentication, content type, caching, client identity |
| Body | The payload for operations that send data |
3. The Parts of a Response
A status code states the outcome class: success, redirection, caller error, or server error. Headers describe the payload and control caching. The body carries the data, conventionally JSON for web APIs.
Well-designed APIs return errors in the same structured shape as successes, so a client can parse a failure as reliably as a result.
4. Common Styles
- REST — resources addressed by path, operations expressed by HTTP method. Ubiquitous and cache-friendly.
- GraphQL — a single endpoint where the client specifies exactly which fields it wants, avoiding over-fetching.
- RPC — endpoints named for actions rather than resources; simple and direct.
- Streaming — long-lived connections that push updates, using server-sent events or websockets.
Most public data APIs are REST or REST-shaped, so that is the style worth learning first.
5. What a Contract Should Guarantee
- Stable field names and types, with additions rather than redefinitions.
- Documented errors, so callers can distinguish retryable from permanent conditions.
- Versioning, so a breaking change does not arrive unannounced.
- Published limits, so a client knows the request rate and payload size it may use.
6. APIs Versus Scraping
An API is a supported, stable interface with an explicit contract. Scraping reads an interface built for humans, where the structure can change without notice.
Prefer an API whenever one exposes the data you need. Scraping is what remains when no API exists, when it omits the fields you need, or when its terms do not fit the use case.
7. Common Misconceptions
- "An API is a URL." It is a contract; the URL is only its address.
- "REST means JSON." REST is an architectural style; the payload format is a separate choice.
- "Status 200 means success." Some APIs return errors inside a 200 body. Always check the payload, not only the status.
- "Undocumented endpoints are fair game." Internal endpoints have no contract and no stability promise, whatever their behaviour today.
8. Summary
An API defines how one program asks another for work, and on the web that means an HTTP request with a method, path, headers, and body, answered by a status and a structured payload.
The contract is the valuable part: stable names, documented errors, explicit versioning, and published limits are what make an interface something you can build on.