By Ronnie Mbuqe
An API defines how one system requests capabilities or data from another. The app sends an agreed request and interprets the returned response.
The visible forecast is only the final presentation. Network access, service rules and the meaning of each returned field all affect what reaches the user.
Your booking timed out after the server had already saved it
The request arrived, the reservation was saved and the reply was lost. The browser sees a timeout, while the booking exists. Repeating the purchase as a new action can now create a duplicate.
This is the API problem we will follow: how two systems describe one intention and recover an uncertain result. No programming experience is needed; the important distinction is between communication status and business status.
Why APIs matter
APIs let different systems talk to each other without exposing everything behind the scenes. Banking apps, weather apps, Google Maps, AI tools, payment systems and booking websites all use APIs.
If an API request times out, does that prove the server did nothing?
A request and its reply are separate events.
Original ExplainItSimply illustration; conceptual, not a scale drawing.Trace the explanation
Losing the reply creates uncertainty about whether the action occurred. For operations such as payment or booking creation, an idempotency contract can let a retry reuse the original result instead of creating a duplicate.
Source and further reading: Stripe documentation
A lost reply does not prove a lost booking
A server can save a booking successfully while its response disappears on the way back. The caller sees a timeout, but the record exists. If it repeats the request as a new operation, the customer may receive two reservations.
An API can support a stable operation identifier so retries refer to the same intention. The server recognises the repeated identifier and returns the existing outcome, subject to the API's contract. This is one practical reason idempotency matters: uncertainty about communication should not automatically duplicate a business action.
Retry the same intention instead of inventing another one
The client sends an operation identifier such as order-17. Under a documented idempotency contract, the server records that identifier with the outcome. A retry with the same identifier and compatible request can return the original result rather than create another booking.
That behaviour is not supplied merely by writing an identifier into a request. The server must implement and document its handling, including mismatched payloads, concurrent retries and retention. The caller also needs a way to retrieve or reconcile the result.
A good interface reports unavailable, invalid and unauthorised outcomes distinctly enough for the user to take a safe next step. Returning a vague failure after every timeout can encourage the very duplicate the design is supposed to prevent.
Two retries refer to the same recorded operation and original booking. How many bookings should this contract create?
This checks a prediction about the worked example. It does not run server code, contact an API or change a booking.
One. The retries repeat the same intention under the stated server contract; an operation label alone is not an implementation.Read the explanation without the checker
One. The retries repeat the same intention under the stated server contract; an operation label alone is not an implementation.
Explain why disabling a button only in the browser cannot enforce this guarantee across reconnects and other devices.
Practical examples: What Is an API
Banking
A banking app requests only the accounts and transactions the signed-in customer may access. The API verifies identity and permission, calls protected services and returns a controlled response. The phone never receives a direct connection to the bank’s database.
Weather
A weather application can send coordinates to a forecast API and receive temperature, rain and wind data in a predictable structure. The provider can improve its internal forecasting systems without forcing every app to understand how the calculations are made.
Travel
A travel site may call separate APIs for rooms, flights, maps and payment. It combines the responses into one customer journey, but must handle changing prices, unavailable providers and partial failure instead of assuming every service responds perfectly.
AI
An AI API receives a prompt and settings, then returns generated output and usage information. The application still controls privacy, moderation, cost, retries and what happens when the model is uncertain; calling the API does not transfer product responsibility to the model.
Read an API request from the outside in
An API becomes easier to understand when you stop thinking of it as a mysterious connection and look at the pieces of one request. A client normally identifies an endpoint, chooses an HTTP method, supplies any required headers or authentication information, and sends data when the operation needs it.
For example, a booking application might send a request containing a resort identifier, dates, party details and an access token. The server checks the request, applies business rules and returns a response. That response may contain availability, prices, validation messages or an error code. The important point is that the two systems agree on the shape and meaning of the exchange.
Request
The request says what the client wants and provides the information needed to process it. A GET request commonly asks for information, while POST commonly sends information that creates or triggers something. Other methods, such as PUT: PATCH and DELETE: communicate different intentions.
Response
The response tells the client what happened. A successful response can contain structured data such as JSON, while a failure may contain a status code and an explanation that the application can use to decide what to show the user or what to try next.
One logical booking request is sent 3 times. With a correctly enforced single-operation idempotency key, how many bookings should that operation create?
Trace the explanation
Three transmissions still represent one logical operation. The server must implement the contract; merely adding a random field to a request does not provide deduplication.
Source and further reading: Stripe documentation
Why is a successful API response sometimes unusable?
A response may be structurally valid but contain missing, stale or unexpected business data. Transport success and a useful result are separate checks.
Verify the status, validate the fields and handle an empty result explicitly. Showing 'no rooms available' should not be the default for every network error.
What happens when an API call fails?
Real systems cannot assume that every API call succeeds. A service may be unavailable, a network connection may time out, credentials may expire, a request may be invalid, or a business rule may reject the operation. Good software treats these outcomes as part of normal system behaviour instead of as impossible events.
Security is also part of the API design. Authentication answers who are you? Authorisation answers what are you allowed to do? A valid login does not automatically give a user permission to read another customer's booking or change a payment. The API should enforce those rules on the server instead of trusting the browser to behave correctly.
Applications may also need retries, timeouts, logging and clear error handling. A retry can help with a temporary network problem, but blindly repeating an operation that creates a payment or booking can create duplicates. That is why reliable APIs often define how repeated requests should be handled.
A contract must describe failure as clearly as success
For a booking request, callers need to know the required dates, guest counts and authentication as well as possible outcomes. 'Unavailable' is different from 'not signed in', and both are different from an unexpected service fault. A caller cannot offer a useful next step if every result is an unexplained string.
A version change also needs care. Renaming a field can break clients that still expect its old name, even if the server's new code is internally correct. Treat the interface as a promise shared by separately deployed systems. Test a realistic request and response, including an invalid case and a retry.
Would disabling Pay twice in the browser guarantee one charge?
No. A client can retry after a timeout or reconnect from another device. The server/payment integration needs an agreed duplicate-prevention strategy and a way to reconcile an uncertain result.
Why API changes need care
An API is a shared boundary, so changing it can affect every application that depends on it. Renaming a field, changing a response format or removing an endpoint may break clients that were built months or years earlier.
Teams therefore use techniques such as versioning, backward-compatible changes, clear documentation and deprecation periods. A well-managed API can evolve internally while giving existing consumers enough time to move to a newer contract.
This is one reason APIs are more than a technical shortcut. They are agreements between systems, and those agreements have to remain understandable and dependable as the software around them changes.
Frequently Asked Questions
Questions about What Is an API?
Is an API a database?
No. An API can talk to a database, but it is not the database itself.
Why not connect directly to the database?
Because APIs protect data, apply rules and control what users are allowed to do.
What should I learn after APIs?
REST APIs are a good next step because they explain common API rules used on the web.
Software In Daily Life
What Happens When You Use WhatsApp, Facebook Or A Shop Till?
Point Of Sale Journey
Why Hosting Matters
A customer retries after a payment timeout. What should the interface say before declaring failure or charging again?
One reasoned response
Acknowledge uncertainty, check operation status and reuse the agreed operation identity when retrying. Do not confuse no reply with a confirmed rejection.
Source and further reading: Stripe documentation
Follow an API request from start to finish
An API is a defined way for one piece of software to request something from another. The caller does not need to know how the other system stores its data internally; it needs to follow the agreed request and response rules. This boundary lets teams change an implementation without forcing every caller to change at the same time.
Example request and response
GET /api/products/42
Accept: application/json
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 42,
"name": "Notebook",
"inStock": true
}
The request asks for product 42. A successful response uses status 200 and returns JSON describing the product. A real API may require authentication, apply rate limits, validate permissions, and return a different status if the product does not exist or the caller is not allowed to see it.
What happens behind the endpoint?
- The client builds the request with a method, path, headers, and sometimes a body.
- The server checks the request, identity, permissions, and input.
- Application logic retrieves or changes data.
- The server returns a status code and a response body, or a useful error.
- The client handles success, failure, timeout, and unexpected responses.
Good API behaviour
Errors should be predictable enough for clients to respond sensibly. A 401 response commonly means authentication is missing or invalid; 403 means the caller is not permitted; 404 means the requested resource was not found; and 500 indicates a server-side failure. Exact conventions depend on the API. Clients should not assume every response is successful just because the network request completed.
Never put secret API keys in public browser code or expose private records because a user knows an endpoint URL. The server must enforce authorisation for each protected operation. Use HTTPS, validate input, avoid returning unnecessary personal data, and document request limits and error formats.
Further reading: MDN: Introduction to server-side development; RFC 9110: HTTP Semantics.
Follow one API request from start to finish
Imagine a weather app asking a server for the forecast in Durban. The app sends a request to a documented endpoint, often including a location parameter and an authentication token if required. The server validates the request, applies its rules, retrieves or calculates the result, and returns a status code plus a response body. The app then checks the status and decides how to display the data.
What can go wrong?
- 400-level response: the request may be missing a required field, contain invalid data, or lack permission.
- 500-level response: the server may have encountered an internal failure.
- Timeout: the network or server may be too slow; repeating a request is not always safe if it changes data.
- Unexpected shape: the response may omit a field or return a value in a different format than the client expects.
Why APIs need contracts
An API contract describes endpoints, inputs, outputs, authentication, error responses and limits. It allows one system to change internally while other systems continue to use the agreed interface. Versioning and clear error messages help developers update clients without guessing. An API is not automatically public or free, and an API key should be treated like a secret rather than embedded in a public page.
When integrating an API, read its official documentation, check the provider's rate limits and data-use terms, handle failures explicitly, and avoid logging tokens or private data. Test both successful responses and the error cases the application must survive.
Sources
Sources and further reading
A closer lookA successful request can still contain no results
A resort search requests units for two adults on particular dates. The service accepts the request and returns an empty list. Another search uses an invalid date and receives a validation error.
Work through the distinction
These outcomes need different messages. No matching availability is a legitimate result, while an invalid date needs correction. An API contract should explain both the response structure and the meaning of an empty collection.
What does an empty successful search establish?
Choose an answer to see feedback. You can try again.
Show the answer and explanation
No matches for those search criteria. These outcomes need different messages. No matching availability is a legitimate result, while an invalid date needs correction. An API contract should explain both the response structure and the meaning of an empty collection.