This post is in my Self Descriptive HTTP API in ASP.NET Core series. It demonstrates how to design an HTTP API like a regular HTML website. Bringing the concepts of links and actions to your API allows your clients to consume it with ease.
If you’re new to this series, here are earlier posts to get up to speed:
If you have any questions, please follow me on Twitter.
In my last post I covered outputting a siren hypermedia payload from our ASP.NET Core MVC application. Specifically I showed linking to each Todo item within the collection.
One aspect of Siren that I mentioned I like is it’s ability to specify actions. This is important for me because it’s what I first started thinking about when working on my most recent HTTP API a couple years ago.
I needed to the ability to tell the consuming client (Angular) about subsequent actions it could take.
Wanting to describe actions in our API responses revolved around permissions and workflow.
For example, if the requesting user didn’t have permissions to perform a specific action, I wanted them to know it. Having this information within the content of your response, we could make the client show or hide certain aspects of the UI depending on the response it received.
Same goes with workflow. Depending on the state of the system, we could conditionally send down links and actions (commands and queries) through our responses to the client.
This made our consuming clients really dumb about workflow. The knowledge about when an action can be performed based off the state of the system was determined by the server.
This is my biggest issue without using hypermedia. Is that the client must understand when it can make calls to particular resources. Meaning it must understand workflow. For me this was incredibly problematic as some of the workflow is non trivial.
This logic already existed on the server for validating if a command/request could be executed based on the current state of the system.
I realize this is a trivial demo, but I hope it gets the very simple idea of the server defining the workflow.
We are going to create another converter for a single Todo. We will provide Actions which allow the client to delete or mark a Todo as complete.
Once a Todo is complete, that action is no longer relevant.
When we access the resource for an individual Todo item, we end up with the following siren payload.
If our client were to then make a call to the complete action, its response, along with any additional call to the previous GET endpoint results in the complete action no longer being returned in the payload.
Hypermedia as the Engine of Application State
This is really what links and actions are all about. Guiding the client to various resources in your API based on the state of the system.
You may of also heard of this with the horrific acronym of HATEOAS.
Regardless, I find the concept incredibly powerful for guiding clients down a path based on the state of your system.
All the source code for my demo is available on GitHub.
Looking ahead we will dig into developing clients consuming our API and the (not) versioning.
If anyone has any other suggestions or recommendations about this series, please leave comment or let me know on twitter.