REST is a well-defined architectural style with a lot of benefits, although often misused describing all kinds of Web APIs, Jimmy Bogard states in a series of blog posts highlighting what’s needed to get a full hypermedia solution from server to client including choosing a hypermedia-rich media type.
Bogard, a Microsoft MVP, emphasizes that REST and hypermedia, a constraint on REST, significantly complicates building both the client and the server API and that he finds it worth the effort only in some scenarios, especially when clients and servers are developed separately from each other. With clients and server in the same source control repository and deployed at the same time, hypermedia doesn’t provide much value for him.
Choosing a media type Bogard sees three options:
- Using a standard.
- Extending a standard.
- Designing your own.
He favours using a standard when possible, noting all the effort put into it, much more than a single project can ever do. Comparing the capabilities of different media types he refers to Mike Amundsen and his H Factor, a measurement of the level of hypermedia support of a media-type, in order to help in selecting the best one for the use case at hand. Often though, he finds that a selected media type doesn’t meet all the needs, resulting in him extending it with the missing pieces.
Bogard thinks the server design and implementation is quite straightforward, comparing it with building a plain JSON API but with the added complexity of a richer hypermedia model. Commonly the implemented API including the selected media type also needs validation from consumers that it is acceptable from a client’s perspective.
Regarding the client side, Bogard notes that most REST examples he looks at contain the server-side API but fails to show real examples of clients consuming the same API. In his example he builds a web client with a basic navigable screen that uses tables of information together with relations and links found in the payload to enable a user to drill down into details. The payload sent by the server contains a lot of metadata and to keep the loose coupling REST provides the client has to be driven by this metadata, but he thinks the client still should be built for a specific purpose; a generic general purpose client would be too boring. Besides building a client using jQuery he also describes the design and implementation of a client built around React, which he finds to be perfect for hypermedia because of its component-oriented nature.