An API works when one system exposes a stable, documented contract that another system can call correctly and securely—so requests are identified, authorised, validated, executed and returned with explicit success, failure and retry semantics while versioning, observability and deprecation keep integrations working as both systems change.
An API—Application Programming Interface—is not merely a URL returning JSON. It is a contracted interaction boundary between independently changing systems. The contract says what capabilities exist, how to ask for them, which inputs are valid, who may call them, what responses mean, what errors look like, which operations are safe to retry and how clients should survive future change.
The API succeeds when two systems can evolve separately without losing their shared ability to communicate correctly.
Quick Read: The Whole API Mechanism
CAPABILITY / RESOURCE → API CONTRACT → ENDPOINT / OPERATION → REQUEST → AUTHENTICATION → AUTHORISATION → VALIDATION → ROUTING → APPLICATION LOGIC → DATABASE / SERVICE → RESPONSE → STATUS / ERROR → RETRY / IDEMPOTENCY → RATE LIMIT / QUOTA → OBSERVABILITY → VERSION / COMPATIBILITY → DEPRECATION → CLIENT MIGRATION → CONTRACT UPDATE
The governing RFE is:
Can one system expose a stable, documented contract that another system can call correctly and securely—so requests are identified, authorised, validated, executed and returned with explicit success, failure and retry semantics while versioning, observability and deprecation keep integrations working as both systems change?
1. An API Exposes a Capability Without Exposing the Whole Implementation
A payment service may expose “create payment”, “get payment status” and “refund payment”. A school system may expose “get timetable” and “record attendance”. A weather service may expose “get forecast for location”.
The caller does not need direct access to the service’s database tables, internal classes or server processes. It needs a stable contract around the capability.
API ≠ implementation.
2. API ≠ User Interface
A user interface is designed primarily for human interaction. An API is designed primarily for software-to-software interaction.
A mobile app may show a timetable to a student through buttons and cards while obtaining the timetable through an API behind the scenes.
3. API ≠ Database
An API can read from or write to a database, but it should not be confused with the database itself.
The API owns the external contract. The database owns persistent operational state. Internal storage can change without forcing every API consumer to change if the contract remains stable.
See How Databases Work for the persistent-state mechanism.
4. The Contract Defines What Callers May Rely On
An API contract can define paths or operations, parameters, request bodies, data types, authentication schemes, response structures, error forms and versioning expectations.
The contract is the shared boundary between provider and consumer. Changing an undocumented implementation detail is usually safe. Changing a contractual field or meaning can break clients.
5. OpenAPI Describes HTTP APIs; It Does Not Run Them
The OpenAPI Specification provides a standard, language-independent way to describe HTTP APIs so humans and software tools can understand service capabilities without inspecting source code or network traffic.
As of August 2026, the latest published OpenAPI Specification is 3.2.0, dated 19 September 2025.
OpenAPI description ≠ running API; documentation ≠ implementation.
6. Endpoint and Operation Are Related but Different
An endpoint is a routable interface location. An operation is the action defined at that location under a method or protocol.
For HTTP APIs, GET /students/123 and DELETE /students/123 share a path while representing different operations.
endpoint ≠ implementation; path ≠ complete operation.
7. HTTP Is a Protocol; REST Is an Architectural Style
HTTP defines request and response semantics, methods, status codes, fields and representations. REST is an architectural style that can be implemented using HTTP.
An API can use HTTP without following every REST constraint. Other APIs may use RPC, GraphQL, event streams, messaging protocols or domain-specific interfaces.
HTTP ≠ REST; JSON ≠ API.
8. A Request Has More Than a URL
An HTTP request can include method, target URI, header fields, authentication credentials, content type, body, correlation identifier and conditional information.
Two requests to the same path can mean different things because the method, body, caller identity or headers differ.
9. Methods Communicate Intended Semantics
HTTP methods have defined semantics. GET requests a representation of a resource. POST asks the target resource to process supplied content according to its own semantics. PUT generally replaces or creates a representation at a known target. DELETE requests removal of the association represented by the target resource.
Method choice matters because clients, caches, gateways and retry systems may behave differently according to those semantics.
10. Authentication Answers “Who Is Calling?”
Authentication establishes an identity or credential context: user, service account, application, device or another principal.
API keys, signed tokens, certificates and delegated-authorisation systems solve different authentication or credential problems.
API key ≠ complete identity model.
11. Authorisation Answers “May This Caller Do This?”
An authenticated caller can still be forbidden from an operation. A teacher may read attendance for their class while being unable to view another school’s records. A customer may read their own order but not another customer’s.
authentication ≠ authorisation.
12. Validation Protects the Contract Boundary
Validation checks whether required fields exist, types and formats are acceptable, identifiers are structurally valid, enumerated values are permitted and request size or other limits are respected.
Validation prevents malformed requests from reaching deeper application logic, but structural validity does not guarantee business validity or real-world truth.
13. Business Rules Live Beyond Basic Input Validation
A booking request can have perfectly valid JSON and still be invalid because the seat is already taken. A payment amount can be numeric yet exceed an authorised limit.
API validation and domain/business validation therefore form different layers.
14. Routing Connects the External Contract to Internal Capability
Gateways, routers and application frameworks map the requested operation to the service or function responsible for executing it.
The internal route can change as systems are refactored while preserving the public API contract.
15. Application Logic Turns the Request Into a State Transition or Read
After authentication, authorisation and validation, application logic may query a database, call another service, perform a calculation, enqueue work or coordinate several systems.
The API boundary should make the outcome observable without forcing callers to understand every internal step.
16. Responses Carry Both Data and Meaning
An API response can include status code, headers, body, resource identifiers, pagination information, retry hints, links or error details.
The body tells the caller about the result. Protocol status tells the caller how to interpret the outcome at the HTTP layer.
17. 200 OK Means the HTTP Request Succeeded Under the Operation’s Semantics
A successful HTTP response does not prove every fact inside the response is correct about the real world.
If a database contains a wrong date of birth, an API can return it perfectly with 200 OK.
200 response ≠ world truth.
18. 201 Created Means a Resource Was Created
RFC 9110 defines 201 Created as indicating that the request was fulfilled and resulted in one or more new resources being created.
Where possible, the response should make the created resource identifiable so clients can retrieve or reference it later.
19. 202 Accepted Does Not Mean Completed
RFC 9110 is explicit: 202 Accepted means a request has been accepted for processing but processing has not completed. It may or may not eventually be acted upon.
Asynchronous APIs therefore need a route to later status—such as a job resource, status endpoint or event notification.
accepted ≠ completed.
20. Errors Need Machine-Readable Semantics
A useful API error distinguishes authentication failure, forbidden action, invalid request, missing resource, conflict, rate limit, dependency failure and internal error.
A human-readable message helps operators. A stable machine-readable code helps clients decide what to do next.
21. Timeout Is an Observation About the Client’s Wait, Not Proof of the Server’s State
A client can time out after the server commits a payment but before the response reaches the client.
The client observed “no response before my deadline”. It did not necessarily observe “operation failed”.
timeout ≠ proof of failure.
22. Retry Is Safe Only When the Operation’s Semantics Make It Safe
Some operations can be repeated without changing the final intended result. Others can create duplicates or double charges.
Retry policy therefore depends on method semantics, application design, operation identity and whether the server can recognise repeated attempts.
retry ≠ automatically safe.
23. Idempotency Protects Repeated Requests From Repeating the Effect
An idempotent operation can be repeated with the same intended effect as one execution. HTTP defines some methods, such as PUT and DELETE, as idempotent at the protocol-semantic level.
For non-idempotent business operations such as payment creation, systems can use a client-generated operation or idempotency key so the server recognises retries and returns the original outcome instead of executing the effect twice.
idempotency ≠ accidental duplicate detection; it should be designed into the contract.
24. Rate Limits Protect Shared Capacity
APIs often limit requests by caller, token, account, operation or time window to protect infrastructure, fairness and cost.
A rate-limited API may still be healthy. The caller has exceeded an allowed consumption policy.
rate limit ≠ outage.
25. Quotas and Rate Limits Solve Different Resource Problems
A rate limit controls how quickly calls occur. A quota can limit total use over a larger accounting period or resource budget.
Both should produce explicit client-visible behaviour rather than unexplained failures.
26. Pagination Makes Large Collections Traversable
An API should not necessarily return one million records in one response. Pagination divides large result sets into manageable windows.
Offset, cursor and keyset pagination have different behaviour under concurrent change. The contract should define how clients continue reliably.
27. Filtering, Sorting and Field Selection Change the View, Not the Canonical State
Query parameters can let clients request only active users, sort by date or select a subset of fields.
The response is a view over authoritative state, not necessarily the complete underlying object.
28. Caching Speeds APIs but Introduces Freshness Questions
Responses can be cached at browsers, gateways, content-delivery networks or application layers.
Caching reduces latency and load, but the contract must respect freshness, invalidation and privacy boundaries.
cached response ≠ current canonical state by default.
29. Observability Shows What Happened Across the Boundary
Logs, metrics and distributed traces help operators understand request volume, latency, errors, dependency failures and which route a request took through several services.
Correlation or trace identifiers allow one user-visible failure to be followed through gateway, application, database and downstream service.
30. Monitoring and Observability Are Related but Not Identical
Monitoring asks whether known conditions are healthy: latency, error rate, saturation, availability. Observability helps investigate unexpected internal states by using emitted signals.
An API needs both known service objectives and enough evidence to diagnose failures that were not predicted in advance.
31. Versioning Manages Contract Change
Clients integrate against assumptions. Removing a field, changing its meaning or rejecting previously valid input can break them.
Versioning strategies may use path versions, media types, headers, date-based versions or compatibility policies. The important job is to make breaking change explicit and governable.
version number ≠ contract quality.
32. Backwards Compatibility Means Old Valid Clients Keep Working
Adding an optional response field can often be backwards compatible if clients tolerate unknown fields. Renaming a required field or changing a value’s meaning is more dangerous.
Compatibility depends on client expectations, not merely on whether the provider believes the change is small.
backwards compatible ≠ identical.
33. Deprecation Creates Time for Migration
When an old operation or version must be removed, a responsible provider announces deprecation, documents the replacement, gives clients a migration window and observes remaining usage.
Immediate removal turns a provider’s internal change into every client’s outage.
34. SDKs Wrap an API; They Are Not the API
An SDK can provide convenient language-specific functions, types, authentication helpers and retry behaviour around an API.
The SDK may lag behind the service or contain its own bugs. The underlying API contract remains the primary interoperability boundary.
SDK ≠ API.
35. Webhooks Reverse the Direction of Notification
Polling repeatedly asks, “Has anything changed?” A webhook lets a service send an event to a registered receiver when something changes.
Webhooks still need authentication or verification, retry semantics, replay protection and idempotent event handling because delivery can fail or occur more than once.
webhook ≠ guaranteed exactly-once delivery; webhook ≠ polling.
36. API Composition Creates Dependency Chains
One API may call three others before replying. This creates a dependency graph in which latency, authentication, quotas and failures can propagate.
Timeout budgets, circuit breakers, fallbacks and partial-response strategies help contain failure, but each changes the user-visible contract and should be designed explicitly.
37. Worked System 1: A Student App Retrieves a Timetable
A student opens an app. The app requests today’s timetable.
STUDENT APP → GET /TIMETABLE → ACCESS TOKEN → AUTHENTICATION → STUDENT AUTHORISATION → DATE VALIDATION → TIMETABLE SERVICE → DATABASE READ → RESPONSE → APP RENDER.
The app never receives direct database credentials. The API controls which timetable data the authenticated student may retrieve.
38. Worked System 2: A Payment Commits but the Response Is Lost
A client sends a payment-creation request. The server validates it, charges the payment and commits the transaction. The network fails before the success response reaches the client.
If the client blindly repeats the POST, a second charge may occur.
A safer route is:
CLIENT-GENERATED OPERATION ID → POST PAYMENT → SERVER STORES OPERATION ID + RESULT → RESPONSE LOST → CLIENT RETRIES SAME ID → SERVER FINDS EXISTING RESULT → RETURNS ORIGINAL PAYMENT → NO SECOND CHARGE.
39. Worked System 3: A New API Version Rolls Out Without Breaking Old Clients
A service needs a richer customer-address model. Existing clients depend on the old response shape.
The provider can introduce additive fields or a new version, publish migration guidance, test known clients, monitor old-version usage and deprecate only after consumers have a viable route forward.
NEW REQUIREMENT → CONTRACT IMPACT ANALYSIS → COMPATIBLE ADDITION OR NEW VERSION → DOCUMENTATION → SANDBOX / TEST → CLIENT MIGRATION → USAGE OBSERVATION → DEPRECATION → RETIREMENT.
40. Worked System 4: A Canonical Knowledge Object Travels Through an API
A client asks for a knowledge object by canonical ID.
The safe route is:
CLIENT → API CONTRACT → AUTHENTICATE → AUTHORISE VISIBILITY → VALIDATE CANONICAL ID → OWNER ROUTE → DATABASE → CURRENT VERSION → RESPONSE METADATA + CONTENT → CLIENT.
A search index can help discover the ID, but the API should still resolve through the canonical owner and authoritative state rather than trusting a stale retrieval copy.
41. Hostile Test: “The POST Request Timed Out, So It Is Safe to Send It Again”
The conclusion is unsafe because the client cannot infer server state from its own timeout.
- Did the server receive the first request?
- Did the operation begin?
- Did it commit before the response was lost?
- Is the operation naturally idempotent?
- Did the request carry an idempotency or operation key?
- Can the client query authoritative status before retrying?
- Will the server return the previous result if the same operation key is seen again?
- Could a retry double-charge, double-book or duplicate a message?
- What timeout and retry policy is documented?
- Which receipt or trace can prove the final state?
“I did not receive the response” and “the operation did not happen” are not the same statement.
Where API Explanations Commonly Break
| Failure | What goes wrong | Repair question |
|---|---|---|
| API-UI collapse | Human interface and machine contract are treated as one layer | Which contract can software rely on independently of the screen? |
| API-database collapse | External consumers depend directly on internal storage | Can storage change without breaking clients? |
| Endpoint-implementation collapse | A route is mistaken for the code behind it | What contract remains stable if implementation changes? |
| OpenAPI-runtime collapse | Description becomes service execution | Does the live API actually conform to the published description? |
| JSON-API collapse | One representation format becomes the whole interface concept | What operations, semantics and error rules exist? |
| HTTP-REST collapse | Using HTTP automatically becomes REST | Which architectural constraints are actually followed? |
| Authentication-authorisation collapse | Known identity becomes permission | May this principal perform this operation on this resource? |
| Validation-business-rule collapse | Valid structure becomes valid action | Which domain invariant still needs checking? |
| 200-truth collapse | Protocol success becomes factual truth | Does authoritative real-world evidence support the returned value? |
| 202-completion collapse | Accepted async work becomes finished work | Where can final status be observed? |
| Timeout-failure collapse | Client wait expiration becomes server failure | What authoritative operation state exists? |
| Retry-safety collapse | Repeating a request is assumed harmless | Is the effect idempotent or keyed? |
| Idempotency-duplicate-check collapse | Ad hoc duplicate detection becomes a contract guarantee | Which operation identity is stable across retries? |
| Rate-limit-outage collapse | Policy rejection becomes service failure | Did the client exceed an explicit consumption rule? |
| Cache-canonical collapse | Fast response copy becomes current truth | What freshness rule and canonical source apply? |
| Version-number quality halo | Newer version becomes automatically better or safer | What contract changed and what clients depend on? |
| SDK-API collapse | Client library becomes the underlying contract | Can the API be understood independently of the SDK? |
| Webhook-exactly-once illusion | Event delivery is assumed singular and guaranteed | Can repeated or delayed events be handled safely? |
| Dependency-chain blindness | One API is treated as isolated from downstream services | Which dependency actually controls latency or failure? |
How to Read Any API
- Capability: What job does the API expose?
- Contract: Which fields, methods and semantics may callers rely on?
- Endpoint: Where is the operation addressed?
- Method / operation: What action is being requested?
- Authentication: Who is calling?
- Authorisation: What may this caller do?
- Validation: Is the request structurally valid?
- Business rule: Is the requested action allowed in current state?
- Execution: Which service or database owns the effect?
- Response: What result is returned?
- Status: Does protocol status mean complete, accepted, rejected or failed?
- Error: Can the client distinguish repairable from terminal failure?
- Retry: Is repeating the operation safe?
- Idempotency: Which key identifies one logical operation?
- Rate limit / quota: What consumption rule applies?
- Pagination: How are large collections traversed?
- Observability: Can one request be traced across dependencies?
- Version: Which contract generation is in use?
- Deprecation: How will clients migrate?
- World return: What authoritative state proves what actually happened?
Current Standards Anchors
- RFC 9110 — HTTP Semantics for the current Internet Standard semantics of HTTP methods, request/response meaning and status codes including 201 and 202.
- OpenAPI Specification 3.2.0 for the current published language-independent specification for describing HTTP APIs, dated 19 September 2025.
Where This Fits in the eduKate Architecture
This article owns the contracted interaction boundary between independently changing systems.
- How Databases Work owns persistent operational state, transactions and recovery.
- How Metadata Works owns structured resource description and interoperability metadata.
- How Networks Work owns how connections move information, resources and effects.
- How Standards Work owns shared specifications and compatibility.
- How AI Works owns data/model inference and generated outputs.
- How Retrieval Works owns how stored knowledge returns when needed.
- How APIs Work owns request/response contracts, authentication/authorisation, retry semantics, versioning and integration reliability.
What This Article Does Not Claim
- It does not make an API identical to a user interface, database or network.
- It does not make JSON equivalent to an API.
- It does not make HTTP equivalent to REST.
- It does not make authentication equivalent to authorisation.
- It does not make a structurally valid request a valid business action.
- It does not make HTTP success proof that returned real-world facts are true.
- It does not make 202 Accepted mean completed.
- It does not make timeout prove that an operation failed.
- It does not make every retry safe.
- It does not make rate limiting equivalent to outage.
- It does not make an SDK the API itself.
- It does not make a published OpenAPI description proof that the live service conforms to it.
Observable Mastery Test
Choose one machine-to-machine interaction: payment, timetable lookup, parcel tracking, weather query, appointment booking or knowledge retrieval.
You understand how APIs work if you can reconstruct:
capability → contract → endpoint / operation → request → authentication → authorisation → validation → internal route → state read/change → response/status → retry/idempotency → rate limit → observability → version → deprecation → client migration.
Then ask five correction questions:
- If the client times out, how can it discover whether the operation actually happened?
- Which operation identifier prevents a retry from creating a duplicate effect?
- Which contract change could silently break an old client?
- Which response is a cache or derived view rather than canonical state?
- What trace, receipt or authoritative state would settle a disagreement between client and server?
An API fails as trustworthy integration infrastructure when its contract is ambiguous, identity and permission collapse together, retries duplicate real effects, errors hide actionable meaning or breaking changes are pushed onto clients without a migration path.
An API is not understood when we can send a request and receive JSON. It is understood when we can explain the contract between systems, who is allowed to invoke it, what each response state actually means, how uncertainty from timeouts and retries is resolved, and how the boundary remains reliable while both sides continue to change.