A small sample used to illustrate some of the benefits of including links inside your next ASP.NET WebAPI implementation.
The API is simple, it allows you to explore a list of books, check books in, and check them out again.
A sample library API along with two clients.
- Api Implementation
- A Resource Driven Client
- A Hypermedia Driven Client
The API makes its way into the public domain, and a couple of wild clients appear (hark, someone is using our API!). We begin to celebrate a little too soon, as now the Grand Library Council has decreed that too many people are checking books out, and never checking them back in. This will not do!
To combat the ever growing pressures of late returns, the workflow of our API must change. Now, users with unpaid fines (due to late returns) must first pay their fines, before checking out any more books.
To simulate the change in this workflow, find the class
InMemoryFineRepository
and flip the magic switch
/// <summary>
/// Switch me to 'true' enable fines
/// </summary>
private static bool _hasFines = false;
We have two wild clients out there, both of which were developed prior to the pay your fines API change. One of these clients will break, and one will survive. Who will win?
The Resource Driven Client has baked-in knowledge of
- The available URI's
- The types being returned from the server
- The workflow of listing books, checking books out, and returning them
It has no knowledge of paying fines, as this was added after the original client was developed.
The Hypermedia Driven client has baked-in knowledge of
- How to find links in a response from the server
- How to follow those links
When a new business rule is enforced, the Resource driven client is not able to tolerate those changes, while the Hypermedia driven client is. This, in a very trivial way, demonstrates the evolvality of the hypermedia client.
This is not designed to be a complete example on how to implement a hypermedia client! It is trivialised significantly. It does not describe how to implement a custom media type, nor does it describe the implementation of hypermedia affordances such as forms. This is a contrived example designed to illustrate a basic evolvability as a property of hypermedia.