RESTful Web API Patterns and Practices Cookbook

Chapter 5. Hypermedia Services

The best software architecture “knows” what changes often and makes that easy.

Paul Clements, Software Architecture in Practice (Pearson)

A primary challenge in designing and implementing APIs for services is balancing usability with evolvability. It is important for service APIs to be clear and easy to understand. At the same time it is critical that these same interfaces be defined in a way that allows for future modifications. Finally, the value of service APIs is often tied to their reliability over time. It’s fine to be able define an API that solves an immediate problem. But as that problem varies over time, operating parameters change, and needs and goals drift over time, that API—ideally—should continue to be useful. That’s a lot to ask of a service interface design!

Tip

Check out “Promoting Stability and Modifiability with Hypermedia Services” for additional discussion on the foundations of creating service interfaces.

As the chapter’s opening quote implies, knowing what changes often in a software design and making that easy is a worthy goal. This is especially true for service APIs. The API is the contract—the promise that needs to be kept.

A great example of this can be found in the way the HTTP protocol was designed. Almost every key aspect of HTTP is modifiable. HTTP methods, status codes, URLs, the list of possible headers, and the list of possible body formats are all abstract collections that can be amended ...