Sponsor: Do you build complex software systems? See how NServiceBus makes it easier to design, build, and manage software systems that use message queues to achieve loose coupling. Get started for free.
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.Actions
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.Workflow
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.Dumb Clients
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.Demo
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.
Great series looking forward to the next article about clients