Jan Mikoláš
Glossary
API: what it is and how it works
An API is more than an HTTP endpoint. It is an agreement between programs covering available operations, data, security, and error states.
Short definition
An API is a contract between two parts of a software system.
API stands for Application Programming Interface. It may be the interface of a library, operating system, hardware service, or an application available over a network. A web API is just one of these cases; an endpoint is a specific entry address for a web API, not the entire API.
With a web API, a client—such as an online store, mobile app, or integration service—sends a request and the provider returns a response. To work together reliably over time, both sides need to agree on a contract: parameters, data formats, permissions, the meaning of errors, and rules for change.
Use cases
What APIs are used for
An API separates the internal workings of a system from the way other programs use its data or functionality.
- connecting an online store to carriers, a payment gateway, accounting software, or a marketplace
- providing a backend for a web or mobile application
- connecting a warehouse, ERP, customer portal, and other internal systems
- repeatable imports, exports, and automated data flows
- calling functions from libraries or operating-system services within a program
Practical example
An online store and a carrier
Once an order has been paid, the online store sends the carrier the shipment details: its internal order number, the recipient address, the shipping service, and, where applicable, a pickup point. The carrier returns a shipment ID and a link to the label, which the store saves with the order.
If the request times out after being sent, the store does not know whether the carrier created the shipment. A safe contract therefore uses a unique sender identifier or an idempotency key. An address error is shown to staff, a temporary error is monitored, and a rate-limited request is retried only according to the instructions from the service.
How it works
From request to response
A simple exchange of data through a web API usually follows these steps:
- Contract The client knows the operation, address, parameters, security rules, and expected responses.
- Request It sends an HTTP method, URL, headers, credentials, and a body where required.
- Processing The service verifies identity, permissions, and inputs before running its business logic.
- Response It returns a status, headers, and data, or a machine-readable error description.
- Client handling The client stores the result or safely handles a temporary error or limit.
Key characteristics
What an API must make clear
JSON alone is not enough. Without the meaning of its fields and rules of behaviour, an interface is not a reliable contract.
Data and documentation
JSON is a common data format, while XML remains prevalent in older B2B, ERP, and logistics integrations. OpenAPI can describe HTTP operations, inputs, responses, and security precisely.
Authentication and authorization
Authentication establishes who is calling; authorization determines what they are allowed to do. An API key, signature, or access token needs a limited scope and lifetime, secure storage, and a way to rotate it.
Errors and limits
The HTTP status should match the outcome. A stable error type and correlation ID are more useful to a client than generic text. Rate limiting must make clear what is counted and when a request may be retried.
Changes and versioning
Adding an optional field is usually more compatible than removing one or changing its meaning. More important than where the version appears are a transition period and a predictable end of support.
Benefits and limitations
What a well-designed API delivers—and what it does not solve
Benefits
- separates the internal implementation from the contract that other systems depend on
- automates data flows without manual exports
- gives different clients a single, defined entry point to the service
- makes it easier to log, measure, and trace individual requests
Common mistakes
- undocumented changes to fields or the meaning of values
- returning HTTP 200 even for errors and relying on free-form text to determine the outcome
- placing keys in URLs or repositories and confusing authentication with authorization
- retrying a mutation after a timeout without protection against duplicates
Scope
An API alone does not make a finished integration.
The network can fail even when the remote side has completed the request successfully. When creating an order or shipment, a blind retry is therefore not enough: you need a unique business identifier, an idempotency key, or a way to look up the current state.
Nor is an interface automatically a secure system boundary. Validation, permissions, auditing, pagination of large lists, and handling an outage of an external service are separate design decisions.
What to consider
Rules for an API that works reliably in production
The contract must also cover situations that do not arise during the first successful call.
- a consistent format for data, times, currencies, and error responses
- HTTPS, limited permissions, rotation, and secure storage of credentials
- pagination, filters, and a maximum limit for large lists
- measurable limits, correlation IDs, logging, and monitoring
- safe retries of mutations under clearly documented rules
Common questions
Common misconceptions about APIs
Is an API the same as an endpoint?
No. An endpoint is a specific entry address for a web API. The API also includes its contract, data models, security, errors, and compatibility rules.
Does an API always use HTTP and JSON?
No. An API may be an interface to a library, an operating system, or a network service. Web APIs often use HTTP and JSON, but may also use XML, other protocols, or asynchronous messages.
What is the difference between an API and a user interface?
A user interface is designed for people. An API is designed for another program, so it needs a precise contract rather than controls.
Does every web API have to be RESTful?
No. REST is a specific architectural style. Another HTTP API, RPC, or asynchronous processing may be a better fit in some cases.
How I use APIs in practice
Integrations are more than a handful of endpoints.
In practice, I connect online stores and internal systems to external services, handling imports, synchronisation, and operational error states.