Quick answer
OpenAPI links let you declare that a value in one response is meant to be used in a later request, connecting operations into a flow instead of leaving them as a flat list. A link can map a returned id into a path or query parameter on the next call, so clients and generated code can follow the workflow without hardcoding field names. Most teams ignore links and hand-write the same extraction in every client; the ones that use them get discoverable, machine-readable workflows. Start with one obvious pair, such as create order then retrieve it by the returned id, and add operation references so the link is unambiguous.
What a link actually declares
A link lives on a response and points at another operation, describing how to build the next request from runtime data. It is not a clickable hyperlink in the HTML sense; it is a runtime expression the client evaluates.
| Part | Purpose |
|---|---|
| operationId / operationRef | Which operation the link targets |
| parameters | Mapping of target parameters to values from the current response |
| requestBody | A value to pass into the next request body |
| runtime expression | Syntax like $response.body#/id that reads the prior response |
A concrete create-to-get flow
First give the operations stable identifiers, then reference the returned id in the link.
The expression $response.body#/orderId tells the client exactly where the next path parameter comes from. A generated client can expose a follow method rather than forcing the developer to remember the field is called orderId.
Links versus other ways to connect calls
| Approach | Discoverability | Client code | Drift risk |
|---|---|---|---|
| Hardcoded extraction | None; buried in code | Manual field access per client | High when fields rename |
| HATEOAS-style URLs in the body | Runtime only | Read a link field | Low, but not in the spec |
| OpenAPI links | In the contract | Generated follow methods | Caught at build time |
Links and in-body hypermedia are complementary rather than competing. Links describe the design-time relationship in the contract; an actual href in the payload helps runtime clients that do not generate code. Mature APIs use both for the same flow.
Practical authoring guidance
- Always reference operationId rather than an operationRef path when possible; it survives path changes and is easier to read.
- Keep every operationId unique across the document, since a link resolves against that identifier.
- Use links for the happy path the documentation teaches, not every possible combination, or the spec becomes noisy.
- Add a description on each link so a human reader understands why the two operations connect.
- Validate expressions after refactors; renaming a response field without updating the link breaks the flow and may not be caught by a schema validator alone.
Using links to drive workflow tests
Beyond generated clients, links give you a reliable backbone for end-to-end tests that walk a real business flow instead of scripting each hop by hand. A generic test can read the link definitions from the contract, execute the first operation, evaluate each runtime expression against the live response, and then invoke the linked operation with the mapped parameters. This does two things at once: it verifies the happy path works against a running service, and it verifies the link expressions themselves still resolve after a refactor. If a field rename breaks a runtime expression, the workflow test fails in CI rather than producing a broken follow call in production. Keep these tests honest by using fresh created resources on each run and asserting both the status and the correlation between the first response and the second request, such as confirming the order id in the path matches the one the create call returned. Treat the link graph as executable documentation; when the tests pass, the contract and the live API agree on the workflow.
What support looks like in tooling
Not every client runtime fully implements links, and some documentation renderers display them minimally. Treat that as a reason to start with the high-value flows rather than avoid the feature. Even where a generator does not produce a follow method, the declared links serve as unambiguous documentation of intended workflow and can drive tests that walk the sequence, asserting the second call succeeds using the id from the first. That alone pays back the small authoring cost.
FAQ
Is an OpenAPI link the same as a link response header?
No. A link is a contract-level declaration describing how to construct a later request from the current response. A Link header is runtime metadata returned over HTTP. They can describe the same relationship but operate at different layers.
Do links make the client automatically follow requests?
They do not force anything; they describe the relationship and parameter mapping. A client or generated SDK may offer a follow helper, but the application still decides whether and when to call the next operation.
What happens if the referenced field is missing?
The runtime expression cannot resolve and the follow call cannot be constructed. Treat a missing id as a failed first operation in your workflow tests rather than proceeding with an undefined parameter.
Can links express a request body for the next call?
Yes. A link can include a requestBody mapping that pulls values from the prior response into the next request body, which is useful for confirm or approve steps that follow an initial create.
This is part of the The OpenAPI Guide — start there for the full set of contract features that make APIs machine-readable.
Top comments (0)