RESTful Web Services Cookbook

Chapter 14. Enabling Discovery

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:

Recipe 14.1

This recipe illustrates what to document to help client developers learn about your web service.

Recipe 14.2

Use this recipe to learn when and how to use the OPTIONS method.

14.1. How to Document RESTful Web Services

The best way to promote design- and development-time discoverability is to unambiguously document the information needed to implement clients.

Problem

You want to know how to document your web service.

Solution

Fully describe ...