Building Hypermedia APIs with HTML5 and Node

Chapter 5. Documenting Hypermedia

We think in generalities, but we live in detail.

- Alfred North Whitehead

Documenting and publishing hypermedia designs makes it possible for the design to gain wider adoption. The process of publishing also can mean attracting expert review that will result in an improved, possibly more useful design. There are a number of organizations that may become involved in the review process including the IANA, W3C, IETF, etc.

This chapter covers a number of the mechanical details of documenting, publishing, and registering media type designs and link relation types. First, a standard for documenting requirements and compliance levels based on the guidelines in RFC 2119 is covered.

Next, the details of writing solid documentation for media type designs of various formats (XML, JSON, HTML) are reviewed. This includes the process of recording the mapping of domain-specific information to media types.

The difference between extending and versioning media types is covered along with the steps for registering media types and link relations with various standards bodies. Finally, a set of design and documentation tips are provided.

Requirements, Compliance, and RFC 2119

When documenting media types, you often need to indicate both to the author and consumers of that type, which elements, if any, are required in a representation (which are optional, etc.). Expressing these requirement levels in a manner that readers can easily understand will go a long way toward making ...