Increasing Resilience with Hypermedia Clients
The more specific the solution, the less reusable it becomes.
Below is an excerpt from my book "RESTful Web API Patterns and Practices Cookbook" from O'Reilly Media
Since computers, as Ted Nelson tells us, "do what you tell them to do," we have a responsibility to pay close attention to what we tell them. There is a tendency to be very explicit when telling computers what to do, and that’s generally a good thing. This is especially true when creating API-driven services. The more accurate our instructions, the more likely it is that the service will act in ways we expect. But client applications operate in a different way.
While API-based services need to be stable and predictable, API client applications need to excel at being adaptable and resilient. Client applications exist to accomplish a task; they have a purpose. It is, therefore, important to be clear about just what that purpose is—and how explicit we want to be when creating the API consumer.
Usability and Reusability
A highly detailed set of instructions for an API client will make it quite effective for its stated job. But it will also render the client API unusable for almost any other task. And, if the target service for which it was designed changes in any meaningful way, that same client application will be "broken." Conversely, if you want to be able to reuse API consumers, you need to change the way you implement them.
It turns out that the more specific the solution, the less reusable it becomes.
Balancing usability (the ease of use for an API) and reusability (the ease of using the same API for another task) is tricky. Abstraction improves reuse. The HTTP protocol is rather abstract (a URL, a set of methods, collection of name-value pairs, and a possible message body in one of many possible formats), and that makes it very reusable. But the HTTP protocol itself is not very usable without lots of supporting technologies, standards, and existing tooling (e.g., web servers and web browsers)
Four Elements
Increasing the resilience of client applications means focusing on some important features of API consumers that improve resilience and adaptability. These are:
A focus on protocols and formats
Resolving interaction details at runtime
Designing differently for machine-to-machine (M2M) interactions
Relying on a semantic vocabulary shared between client and server
As a group, these four elements make up a set of practices that lead to stable API consumers that do not "break" when service elements like protocol details, resource URLs, message schema, and operation workflow change over time.