2026-09-24 · 8 min read
- openapi
- api
- documentation
An OpenAPI Link connects a response from one operation to a possible follow-up operation. Its parameter values or request body can use runtime expressions that read details from the source request or response.
Links enrich documentation and tooling; they do not call the target operation, carry authentication, or bypass its contract. Reliable links require stable operation identity, concrete response shapes, exact serialization, and independent target authorization.
Choose a stable target
Reference the target with operationId when it is unique and governed across the document, or use operationRef when a URI reference is more appropriate. Define ownership and compatibility rules so refactors cannot silently leave links pointing at missing or different operations.
- Use exactly one target mechanism per link.
- Lint operationId values for uniqueness.
- Resolve external references in a controlled registry.
- Test links after bundling and code generation.
Resolve expressions against real responses
For each linked status and media type, provide a synthetic response fixture and resolve every expression by hand. Distinguish source request path, query, header and body values from response header and body values, and escape JSON Pointer tokens correctly.
Define missing, null, array, object, and type-mismatch behavior in the surrounding API workflow. A schema default or example does not mean a value existed in the runtime response.
Map target inputs exactly
Link parameter keys must correspond to parameters on the target operation. Match names and locations, then let the target parameter's style, explode, and allowReserved settings govern serialization rather than pre-encoding a value in the expression.
For a linked request body, ensure the resolved value matches a supported target media type and schema. Keep identifiers opaque where possible and do not combine untrusted fragments into arbitrary destinations.
Preserve authorization boundaries
Document the target operation's security separately. The client must obtain suitable authorization, and the server must verify tenant ownership, object access, input validation, rate limits, and replay or idempotency policy on every follow-up request.
Do not put credentials, production identifiers, expiring signed URLs, or personal data into link examples. A relationship visible in API documentation is not evidence that every caller may traverse it.
Verify the tooling pipeline
Use Flashman's YAML/JSON converter for the contract, JSON formatter for fixtures, URL tool for harmless parameter values, diff for rendered or generated artifacts, and hash tool for public fixture identity.
Test each response and media type, all expression sources, escaped field names, missing and null values, arrays, external references, operation renames, parameter encoding, target validation errors, authorization denial, bundler output, documentation renderers, and generator upgrades.