When building RESTful web services, you need to address two kinds of discoverability. These are design-time discoverability and runtime discoverability. Design-time discoverability helps others design and build clients. It describes all the essentials that client developer teams and administrators need to know in order to build and launch clients. Runtime discoverability, on the other hand, helps maintain loose coupling between clients and servers and enables plug-and-play-style automation. Runtime discovery involves HTTP’s uniform interface, media types, links, and link relations. This chapter is about design-time discoverability.
Design-time discoverability simply means describing your web service in prose, whether such prose is generated by some tools or created manually by the designers or developers of the web service. Client developers can consult this prose to understand the “semantics” of the resources, media types, link relations, and so on, and implement clients.
This chapter discusses the following recipes:
The best way to promote design- and development-time discoverability is to unambiguously document the information needed to implement clients.
You want to know how to document your web service.
Fully describe ...