Developing software in the Real World

Using Fractal as your OpenWhisk API's view layer

When writing an API, it’s common to produce an output that conforms to a known media type such as JSON API or HAL, etc. I’m a strong believer that even though I’m writing an API, my application has a view layer. It’s not the same as building an HTML page, but you still need to separate out the code that creates the structured output from your model layer. For a couple of APIs that I’ve written recently, I’ve used Fractal for this.

Using Fractal

To use Fractal, you need some data. This can be a single entity or a list of entities. You then put your entity into Fractal Item or your list into a Collection and then transform it.

The magic of Fractal is in the Transformer which is where you tell Fractal how to interpret the model data.

This is my TodoTransformer:

The transform method receives our entity and returns an array describing how we would like it to be presented to the world. This is the key decoupling between our model layer and our view.

Plugging Fractal into OpenWhisk

To use this in OpenWhisk, I choose to use my DI container that I have discussed previously. Within my AppContainer, I need two factories: one for the Manager and one for the Transformer.

Let’s start with the Transformer’s factory:

The only complexity here is that we need the base_url. As this is an OpenWhisk API using API Gateway, I referenced Lorna Mitchell’s article Relative Links with IBM Cloud API Gateway, which applies to Apache OpenWhisk too.

From this, we know that the full URL that was used for this action is in $args['__ow_headers']['x-forwarded-url'], however we need to do a little bit of work to ensure that we remove any extra path segments such as the todo’s id. We do this by removing the __ow_path value from the end of the x-forwarded-for header:

The Manager factory is very few lines:

Serializers are the way that Fractal structures your data. It comes with a number of different ones including JsonApiSerializer which supports JSON-API. In this case, I want the simplest possible formatting, which is ArraySerializer.

Using Fractal in an action

To put this into our action, we grab the objects from the container and use them:

Our action now renders structured data for our API clients.


Separating the rendering of your API data from your model code makes for a much more maintainable application. This is also valid in serverless applications and Fractal provides for a clean way to do this.

One thought on “Using Fractal as your OpenWhisk API's view layer

Thoughts? Leave a reply

Your email address will not be published. Required fields are marked *