What Is an API? A Clear Explanation for People Who Keep Nodding Along
The contract that lets one piece of software ask another for something.
6 min read
Loading…
The contract that lets one piece of software ask another for something.
You have almost certainly heard an API described as a waiter taking your order to the kitchen. It is a fine metaphor for about eleven seconds, after which it explains nothing about why the integration you are waiting on has taken three weeks.
Here is a more useful definition. An API is a published contract: a list of requests one program promises to accept, and what it promises to send back. That is the whole idea. Everything else is detail about how the contract is expressed.
The contract framing matters because it explains the things people actually run into — why APIs have versions, why they break, why documentation is not optional, and why a good one feels obvious while a bad one feels like archaeology.
Most APIs you will meet are web APIs speaking HTTP, the same protocol your browser uses. A request has four visible parts, and understanding them is genuinely most of the battle.
A verb saying what kind of operation this is. GET retrieves something and should change nothing. POST creates. PUT and PATCH update. DELETE removes. The convention is not decoration — infrastructure everywhere assumes a GET is safe to retry and cache.
Which resource you are talking about. In a well-designed API these read as nouns in a hierarchy: /authors/42/posts is legible without documentation. Endpoints named after actions — /doAuthorPostFetch — are the first sign you are in for a long afternoon.
Metadata about the request: who you are (authentication), what format you want back, what format you are sending. Most authentication failures are a missing or malformed header, which is why they are so maddening to debug.
The data itself, usually JSON, sent when creating or updating something. GET requests do not have one.
Key takeaways
An API is a published contract for what one program will accept and return.
Method, URL, headers and body are the four parts of nearly every web request.
Status codes tell you which side of the conversation the problem is on: 4xx is yours, 5xx is theirs.
Authentication belongs in a header, never in the URL.
Rate limits, pagination and versioning are the three things people forget until production.
The response carries a status code, headers and usually a body. The status code is the fastest diagnostic tool you have, and its first digit tells you where to look.
Range | Meaning | Who needs to fix it |
|---|---|---|
2xx | Success | nobody — it worked |
3xx | Redirection | usually handled automatically |
4xx | Your request was wrong | you: bad data, missing auth, wrong URL |
5xx | Their server failed | them, though you should retry sensibly |
Two are worth memorising because they are constantly confused. 401 Unauthorized means the server does not know who you are — your credentials are missing or invalid. 403 Forbidden means it knows exactly who you are and you are not allowed. One is a login problem; the other is a permissions problem.
REST is a set of conventions, not a technology. An API described as RESTful generally means: resources are addressed by URL, HTTP methods carry the meaning of the operation, responses are JSON, and each request contains everything needed to serve it — the server keeps no memory of your last call.
That last property, statelessness, is why web APIs scale. Any server in a pool can answer any request, because nothing is remembered between them. It is also why you send your credentials on every single call rather than logging in once.
On the alternatives
REST is the default, not the only option. GraphQL lets a client request exactly the fields it needs in one query, which suits complex front-ends. gRPC is faster and strongly typed, and is common for service-to-service traffic inside a system. Webhooks invert the direction entirely — the server calls you when something happens, instead of you polling to ask.
Almost every API caps how many requests you may make. Exceed it and you get 429 Too Many Requests. Handle it by backing off and retrying with an increasing delay rather than hammering the endpoint, which in most systems extends the block.
An endpoint returning a list will not return all of it. It returns a page, and a way to ask for the next one. Code written against a test account with 12 records and no pagination handling will silently process only the first 50 of a real customer's 4,000.
Contracts change. Well-run APIs version explicitly — /v1/, /v2/ — so existing clients keep working while new ones get new behaviour. When you consume an API, pin to a version and read the deprecation notices. When you publish one, remember that a field rename is a breaking change for everybody.
Best practice
Never put an API key in a URL. Query strings are logged by servers, proxies, browsers and analytics tools, and those logs are rarely as protected as your secrets should be. Credentials belong in headers, and API keys belong in environment variables rather than in your source code.
The difference between a pleasant integration and a three-week one is mostly visible on day one.
Predictable naming. Once you have seen two endpoints you can guess the third.
Honest errors. A useful error says which field was wrong and why, not just invalid request.
Consistent shapes. The same entity looks the same everywhere it appears.
Documentation with real examples. A copy-pasteable request beats a reference table.
A sandbox. Somewhere to make mistakes without consequences.
Stable versioning. Nothing changes underneath a working integration without warning.
Case study: the integration that failed at month end
A small logistics team integrated a carrier's tracking API. It worked flawlessly in testing and for the first three weeks of live use. On the last day of the month it failed completely for four hours.
Two things had combined. Their code fetched every shipment in a loop with no pagination handling, and month end produced far more shipments than any test had. That volume tripped the carrier's rate limit, and their error handling retried immediately, in a tight loop, which extended the block.
The fix was small: honour the pagination cursor, respect the retry-after header, and back off exponentially. All three were documented from the start. Nobody had read that page because the happy path had worked.
Watch out
Test data is almost always smaller, cleaner and better behaved than production data. Pagination bugs, rate limits and timeout handling are invisible until real volume arrives — which is usually at the worst possible moment.
Learn these three and most API debugging becomes straightforward.
An API is a contract. A web request carries a method, a URL, headers and sometimes a body; the response carries a status code that tells you which side of the conversation went wrong. REST is a set of conventions built on HTTP, and rate limits, pagination and versioning are the practical realities that decide whether your integration survives real traffic.
You do not need to memorise every status code or debate REST purism. You need to be able to read a request, understand what the response is telling you, and remember that the documentation page you skipped is where the production incident is described in advance.
If you are building rather than consuming, the same contract mindset applies — and our guide to web application security fundamentals covers the authentication and validation side that every public API has to get right.
Tap a star to share what you thought.
No ratings yet
A published contract between two pieces of software: a defined set of requests one program agrees to accept, and what it will send back. It lets systems use each other's functionality without knowing how the other is built internally.
An API is the general concept of a programmatic interface. REST is one popular style of building web APIs, using HTTP methods, resource-based URLs, JSON responses and stateless requests. Not all APIs are REST APIs.
A 401 means the server does not know who you are — credentials are missing, malformed or expired. A 403 means it knows who you are and you are not permitted to do this. The first is an authentication problem, the second a permissions one.
Sign in to join the conversation.
Loading responses…
Have a story, idea, or something valuable to share? Join The Blog Story for free, publish your content, reach more readers, and earn a share of advertising revenue from eligible content.
Create quality content. Grow your audience. Grow your earning potential.
A secret string identifying your application to a service. Keep it in an environment variable or secrets manager, send it in a request header, and never put it in a URL or commit it to source control — URLs end up in logs that are far less protected than the key.
A cap on how many requests you may make in a given period. Exceeding it returns a 429 response. Handle it by respecting any retry-after header and backing off with increasing delays rather than retrying immediately in a loop.
List endpoints return results in pages rather than all at once. Code that ignores pagination works perfectly against a small test account and then silently processes only the first page of a large customer's data — a bug that appears only at scale.
Because the contract changes over time, and existing clients would break. Versioning lets a provider ship new behaviour under a new version while old integrations keep working against the old one.
The inverse of a normal API call: instead of you asking repeatedly whether something has happened, the provider sends a request to a URL you supply when the event occurs. It is far more efficient than polling for infrequent events.