In my last post, I discussed the need to document resources through vocabularies.  By leveraging vocabularies, you can provide separate documents which describe the APIs resource representations and behaviors, however you aren’t quite yet capable of presenting a uniform interface.  In this post I’ll go through the final piece we need in order to present a uniform interface to facilitate a completely discoverable hypermedia web api; a Home document.

There are a few names which have been floated to describe this resource, root document, directory, index, and home document to name a few.  The name isn’t terribly important, however the important part is to present the single valid entry point from which all clients MUST discover your APIs resources and functionality.  The Home Document specification is a great example of one method for providing the discoverability of all resources and meta-data for your service.  There are many added functionalities, but the root of the document is a list of root resources and meta-data through which a client can begin to interact and discover your API.

Another very important role of the home document is to provide a starting point to expose multiple dimensions of negotiation the service supports.  These dimensions would include the media type, goals, and even vocabularies in addition to more standard protocol negotiation elements.

By utilizing the home document, a hypermedia web api can present the uniform interface it needs to provide robust flexibility and discoverability for consumers of all types.