To take full advantage of the benefits of hypermedia driven systems, the client must allow the server to take the lead and drive the state of the client, Darrel Miller writes and compares a hypermedia API with dancing; it takes two to Tango.
Darrel describes how a quick way for two people to get into dancing is to learn a choreographed sequence of steps for one specific song. Basically the end result is that they individually can dance the steps while hanging on to each other. The drawback is that they know the steps for one song and with one partner only. Problems appear with change, a new song or a new partner will reveal their lack of dancing skills.
Similarly, when consuming a HTTP API the application can be like the choreographed dance, both the client and server know what is going to happen. When the client makes an HTTP request it knows how the server will respond. Darrel claims that this is how we during the last twenty years have been building distributed applications. We first learn the API that the server exposes and then teach our clients an intricate pattern of interactions in order to achieve the goals.
In order to really know how to dance, Darrel explains that it is essential to be able to dance to whatever music is played and this can be done by learning a set of basic dance primitives. When a couple is dancing it’s also important that one is leading and the other follows, The one that leads chooses the sequences of primitives to perform and uses hand signals and body position to communicate what is coming next. There is no predefined, choreographed set of sequences, only the constraints of the dance style
Correspondingly, for a HTTP API implemented according to the same principles, the client no longer need to keep track of state, instead it simply follows the lead of the server by understanding the messages received and trusts the server to provide the necessary guidance. New or changed business requirements not affecting resources means there is no implication on the client. With many different clients this is a significant advantage according to Darrel.
Darrel has published a complete WPF example in the Github repository.