RESTful Web API Patterns and Practices Cookbook

Chapter 7. Hypermedia Workflow

Productivity is never an accident. It is always the result of a commitment to excellence, intelligent planning, and focused effort.

Paul J. Meyer

For many, the ultimate goal of creating service interface APIs is to foster flexible and robust workflow solutions that mix existing services in unique ways to solve new problems. In fact, this goal is embodied in the keystone principle discussed in “Shared Principles for Scalable Services on the Web”. The process of linking services together is not a great challenge when these services were designed from the start to work in concert. However, enlisting services that were not built as a group, know nothing of each other, and are oblivious to the solution being created is a much bigger challenge. This second approach depends on important implementation details that make a number of activities possible, such as sharing solution state, progressing through multiple steps to accomplish a goal, and tracking/displaying that progress. Anytime you mix service interfaces together, there is a chance of execution errors that might require rerunning some steps, undoing others, and knowing when this is needed.

Often, we build our own services as a related collection. In fact, if the same team is building more than one service, those services are bound to have hidden dependencies that are difficult to untangle. Keeping this tangle at bay takes discipline, design, and determination.

The bad news is that designing ...