Relationships in a header rather than a body. Underused, and the quiet workhorse of pagination and deprecation notices.
Link
Representation Metadata IANA permanent response 2 spellings
Link carries typed relationships to other resources without touching the payload — next and prev for pagination, describedby for a schema, deprecation for a migration guide, license for terms. It is the most versatile underused header in HTTP.
Ninety-eight providers declare it, which puts it tenth in the catalog and still well below where it should be. Most APIs that paginate do it with body envelopes, which works but bakes navigation into the schema and makes it something every client must learn separately.
The registry
Listed in the IANA HTTP Field Name Registry as a permanent entry. Defined in RFC 8288: Web Linking.
In the catalog
Declared by 98 providers across 4,269 published specification files in the API Evangelist catalog, where it appears as a response header — sent by the server.
It is spelled 2 different ways across those contracts — Link, link. HTTP field names are case-insensitive (RFC 9110, §5.1), so every one of these is the same header. They are not the same string, which is why generated clients disagree about it.
Using it
Use registered relation types where they exist rather than inventing your own. Pair it with Deprecation — rel="deprecation" pointing at the migration guide is the difference between a machine-readable warning and a machine-readable warning a human can act on. Declare it in components.headers so it shows up in generated documentation.
Governed by these rules
Machine-enforceable governance rules from rules.apievangelist.com that apply to this header when it appears in an OpenAPI.
OpenAPI Components Headers Error error
Utilizing the headers object in the centralized OpenAPI components library helps make headers reusable across API requests and responses
Guidance: Rate Limits →OpenAPI Components Headers Info info
Utilizing the headers object in the centralized OpenAPI components library helps make headers reusable across API requests and responses
Guidance: Rate Limits →OpenAPI Headers Hyphenated Pascal Case error
HTTP headers should follow Hyphenated-Pascal-Case naming convention for consistency and readability, such as Content-Type, X-Request-Id, or Accept-Language.
Guidance: Naming →