Designing Hypermedia and State Lifecycle Driven APIs with Jargon

A rich state lifecycle is the foundation for a hypermedia-driven API

Jargon is a platform for creating data models and APIs using Domain Driven Design. In this article we’ll:

• create a state lifecycle that will advertise what actions can be taken on a Shopping Cart
• using the states from the lifecycle as the status code for a the Shopping Cart resource
• create a simple API specification that uses hypermedia to advertise the allowable actions that can be taken on a Shopping Cart
• putting that all together into a Readme

Before all that, let’s do a quick deep-dive into hypermedia.

Hypermedia for dummies

Hypermedia is quite a detailed topic, but here’s a very rough crash-course to make sure we’re all on the same page.

Here’s my unofficial definition: a technique that makes systems easier to use by adding details that tell consumers what actions they can take next.

It’s a technique that’s not limited to APIs, and I’m willing to bet that you’ve used it already on countless websites without even knowing. Here’s an example of hypermedia in action:

See those CHANGE and CANCEL buttons? That’s hypermedia

See those CHANGE and CANCEL buttons? That’s hypermedia.

Let’s quickly think about why those buttons are there. The creator of the website has some internal process in mind that they’re helping you transition through by advertising where you’re currently up to in the process, and the steps you can take next.

They’ve described those actions in words that you, the consumer, can understand and infer what will happen if you click them.

It also works in reverse. Here’s the same screenshot, but without one of the advertised actions. It makes it pretty clear that you can’t change the booking right now.

It’s pretty clear that you can’t’ change this booking. At least at the moment.

So now you know: that’s hypermedia (or at least enough to continue on with the story).

The elephant in the room

Hypermedia as in the above examples works because the consumer of the service is an intelligent actor — ie: you. You look at the screen and work out from the UX what is allowed and what isn’t. This setup works great for humans who can observe and evaluate their environment — but less so for machines. This doesn’t mean that hypermedia can’t be used to improve API designs — quite the opposite, but it does mean we need to think a little differently about what problem we use hypermedia to solve in an API context.

Examining a state lifecycle

Ok, now we’re all on the same page about what hypermedia is, let’s take a look at how to design an API that uses it.

It all starts with a state lifecycle, something that describes the behaviour of a resource within a Domain. We’ll be updating the fictional online store domain that is covered in our Worked example of using Jargon for Domain Driven Design, specifically by adding a lifecycle for the Shopping Cart resource. It’s going to look like this:

The completed Shopping Cart state lifecycle diagram.

Let’s quickly go through what the different things on the diagram mean.

1. The blue circle at the top is the initial state — it’s the pseudo state the resource is created in.
2. The green and red circles are the final states — green for successful, red for failure. Once a Resource enters one of these states, it stays there forever — its job is done.
3. The rectangles are the states that a Resource can be in (New Cart, Updated, etc). Entering into some of these states can trigger an event that should be broadcast to others who are interested. States that broadcast an event have the name of the event they broadcast underneath the name of the state, surrounded by {}
4. The lines are the transitions between states. These transitions are a mix publicly available commands (that can come from outside the Domain), and private transitions (that can only com from inside the Domain)

Ok, now we know the nomenclature, let’s describe a little bit of what the diagram is telling us:

• The {purchase} command can be used to move the cart to purchased
• The Domain can, after a period of inactivity, abandon the cart
• Whenever a new cart is created, emit a CartCreated event

Creating a state lifecycle

Now that we know some of what is happening, we should be able to read the code that generates this lifecycle. To create a new lifecycle, click the ‘Create a State Lifecycle’ button in the artefacts tab.

The code for the Shopping Cart example looks like this.
Based on the above descriptions, you should be able to infer what is happening — leave a comment if you would like some help.

As you type, Jargon will update the diagram, and show you a list of the states, commands and events that are used:

Using a State Lifecycle within a Domain

Now that we’ve created a state lifecycle, let’s update the Shopping Cart resource to include a ‘status’ property, that uses the values of the states from this lifecycle.

In the Domain editor, create a new code table, call it ‘ShoppingCartStatus’ and select ‘State Lifecycle’.

Jargon will fetch all the lifecycles for this Domain, and let you select which one this code table should be based on:

Add a new property to ShoppingCart called status, that uses the new ShoppingCartStatus code:

Creating Hypermedia API paths

Now that we’ve added a lifecycle code table as a property of ShoppingCart, whenever we create an API path for ShoppingCart, Jargon will identify that is driven by a lifecycle, and allow you to select ‘State Transitions’ as a type of action that can be taken.

Now follow the steps outlined in Creating OpenAPI specifications in Jargon to create an API specification. You will notice that Jargon has added in a collection of paths that correlate to the public commands that were described in the state lifecycle, which you can enrich and describe like any other API path:

Looking at the hypermedia within the API specification

Opening up the generated API specification, we can see that Jargon has added a new ‘links’ object to all the paths that operate on Shopping Carts:

This links object is the API advertising what hypermedia actions can be taken. In this example, there is a ‘purchase’ action (that correlates to the ‘action’ command from the lifecycle). It also informs API consumers what operation to call to fulful the ‘purchase’ action, and what parameters you will need to provide:

Wrapping up

So that’s a brief overview of hypermedia, and how Jargon can help you design Domains that use it to generate APIs that are easier for developers to use.

The Domain from this article is available on the public Jargon instance, along with the API specification.

If you’re interested in getting started with Jargon, or hypermedia APIs, why not create a free account and try it out.

If you have any questions, or spot any errors, please:

• leave a comment below, or
• raise an issue at the jargon issue tracker GitHub repository