The following sections provide conceptual overviews of various components that support the Representor Pattern and links to their evolving design documents.
Representor instances will provide a simple state-machine interface for interacting with hypermedia messages in a consistent fashion.
Because these objects are designed to be a canonical representation of remote Hypermedia resources, they are effectively a "rosetta stone" of Hypermedia. That is, different media types may be mapped to and from the structure for use in consuming and generating Hypermedia messages in multiple formats.
The Representor interface includes:
- Miscellaneous metadata about the message.
- The set of Transition objects available at runtime in the message.
- Data attributes of the message.
- Nested representors in the message associated with embedded resource representations.
Transition instances encapsulate information about interacting with links and forms (or their equivalents in a particular generic hypermedia type) in a Hypermedia message. For media types that support embedding protocol specific information in the message, Transition instances will abstract protocol specifics and allow interacting with the state-machine transition in a protocol and media type independent fashion.
The Transition interface includes:
- Miscellaneous metadata about the transition including protocol details.
- The URI of the transition.
- Parameters associated with a URI template, if any, including any validators on the values.
- Attributes associated with request bodies, if any, including any validators on the values.
Internally, Representors will have a robust structure to accommodate mapping diverse Hypermedia media types. In order to not pollute the interface of Representor instances with this structure, a builder pattern will be scoped that allows construction of diverse messages via a [Representor Builder][] class.
The interface includes:
- Methods to add metadata.
- Methods to build and add transitions.
- Methods to add attributes.
- Methods to nest Representors.
Using simple factory patterns and writing serializer/deserializer pairs for different media types will allow both translating server-side data into hypermedia representations and server responses into client-side Representor instances.
Server-side, a representation can be constructed using the Representor Builder from combinations of data from models, etc. By then using a serialization factory, the constructed representation can injected into a serializer for a particular media type. Using the specification of the associated media type and iterating over the Representor state-machine interface, a particular media type response can be rendered.
Client-side, a hypermedia agent can use a deserializer factory to convert a server response to a Representor instance. In this case, a deserializer would use the media type specification and the RepresentorBuilder to construct and return a Representor instance.
With the aforementioned functionality, the elusive general-purpose Hypermedia client becomes a trivial Representor wrapper that is able to invoke transitions for implemented protocols.
By using the Representor interface and various serialization factories, the complexities of testing different Hypermedia APIs can be abstracted into general purpose step definitions that re-enforce properly consuming Hypermedia APIs.
In the simplest case, services can code the translation of data into a Representor using the builder and then easily render it as a response for a particular media type. In more advanced cases, server-side frameworks can also be implemented in like fashion that allow generic mapping of data into hypermedia responses.
The following outlines the initial priorities for the project:
- Isolate the common elements of generic Hypermedia media types to from the internal structure of Representors.
- Implement state-machine interface and builder pattern for Representors.
- Implement serializer/deserializer factories for diverse media types.
- Implement simple Hypermedia agents.
- Implement testing support.