Theme Durable integration contracts
REST API in brief
A REST API is an HTTP-based interface that treats business information as resources and transfers representations of their state. The client uses a uniform set of HTTP semantics instead of needing to understand the server’s internal code or database.
In context
REST is an architectural style, not a product format and not a synonym for “JSON over HTTP”. An API can use HTTP and JSON while undermining REST through session-dependent calls, unclear resources or methods whose behaviour conflicts with HTTP semantics.
The resource matters more than the endpoint
GET /assets/42 retrieves a representation of asset 42. PUT can replace intended state, POST can ask a resource to process content and DELETE requests removal of the association with a resource. RFC 9110 defines method semantics, including safety and idempotency. The API contract must still describe the business rules.
A durable API does not publish the database. It publishes a capability with an owner.
The contract has more layers than JSON
- Identity: stable URIs and keys for resources consumers actually need.
- Semantics: method, status code, field meaning, unit and allowed state transitions.
- Operations: limits, pagination, timeouts, retries, idempotency keys and observability.
- Change: compatibility rules, deprecation, version policy and consumer dialogue.
- Trust: TLS, authentication, authorisation, data minimisation and logging policy.
OpenAPI makes the surface machine-readable
The OpenAPI Specification defines a language-agnostic interface description for HTTP APIs so humans and tools can understand service capabilities without source code or traffic inspection. It can drive documentation, client generation and testing. It is not, by itself, the truth about business meaning or production behaviour. Contract tests and operational measurements are needed to verify that the implementation keeps its promise.
REST API or event flow?
Use a REST API when a consumer wants to query or affect known resource state and needs a direct response. Use MQTT, for example, when a producer announces that something happened without knowing the recipients. Mature architectures often combine both: the event signals change, while the API provides an authoritative current representation.
Review before release
- Can an outsider name the resource and its owner?
- Do methods, status codes and caching follow intended HTTP semantics?
- Are retries safe, and has idempotency been designed explicitly?
- Does OpenAPI describe successful responses, known errors and security requirements?
- Are compatibility tests, deprecation windows and usage metrics in place?
- Is the minimum necessary data exposed to the minimum necessary privilege?
HubMind’s view
Treat the API as a long-lived product boundary, not the project’s final integration task. Give every resource semantics, ownership and a measurable lifecycle promise. Systems can then evolve independently without leaving consumers in the dark.
Related concepts
Related: API, JSON, data governance and information modelling.
Scope and freshness
This page describes REST as an architectural style, HTTP semantics under RFC 9110 and the current OpenAPI Specification. Reviewed 31 August 2026; review again after a material HTTP or OpenAPI specification change.