Hypermedia links are becoming an increasingly important part of the web, in both HTML contexts
and various API format contexts. However, there is no single common hypermedia format, nor
is there a common way to represent Links between formats.
This specification aims to provide PHP developers with a simple, common way of representing a
hypermedia link independently of the serialization format that is used. That in turn allows
a system to serialize a response with hypermedia links into one or more wire formats independently
of the process of deciding what those links should be.
One of the key targets for this specification is PSR-7 Response objects. Response objects by design must be
immutable. Other value-object implementations likely would also require an immutable interface.
Additionally, some Link Provider objects may not be value objects but other objects within a given
domain, which are able to generate Links on the fly, perhaps off of a database result or other underlying
representation. In those cases a writeable provider definition would be incompatible.
Therefore, this specification splits accessor methods and evolvable methods into separate interfaces,
allowing objects to implement just the read-only or evolvable versions as appropriate to their use case.
Different hypermedia standards handle multiple links with the same relationship differently. Some have a single
link that has multiple rel’s defined. Others have a single rel entry that then contains multiple links.
Defining each Link uniquely but allowing it to have multiple rels provides a most-compatible-denominator definition.
A single LinkInterface object may be serialized to one or more link entries in a given hypermedia format, as
appropriate. However, specifying multiple link objects each with a single rel yet the same URI is also legal, and
a hypermedia format can serialize that as appropriate, too.
In many contexts, a set of links will be attached to some other object. Those objects may be used in situations
where all that is relevant is their links, or some subset of their links. For example, various different value
objects may be defined that represent different REST formats such as HAL, JSON-LD, or Atom. It may be useful
to extract those links from such an object uniformly for further processing. For instance, next/previous links
may be extracted from an object and added to a PSR-7 Response object as Link headers. Alternatively, many links
would make sense to represent with a “preload” link relationship, which would indicate to an HTTP 2-compatible
web server that the linked resources should be streamed to a client in anticipation of a subsequent request.
All of those cases are independent of the payload or encoding of the object. By providing a common interface
to access such links, we enable generic handling of the links themselves regardless of the value object or
domain object that is producing them.