UI Morph

We close this year with some thoughts about User Interfaces
and why we chose to re-write ours in AngularJS.

Two weeks ago Stormpath released our new Angular-based UI and our customers were so
excited that they wrote in to thank us for the early Christmas present. Nice! In the
spirit of sharing, here is our story of how this UI miracle came to be.

Update: Stormpath now secures Angularjs apps with token authentication!

Designing User Interfaces for RESTful Services

The Stormpath API models a problem: how do you store user data, manage
passwords, group memberships, and other custom user data? Our API represents a
thought-out solution to this problem, using RESTful conventions.

For a RESTful API service, the user interface (UI) should exist as a convenience and
conceptual layer on top of the API. The UI should allow your customers to explore the concepts
of your API and manipulate any persistent state stored behind your API.
It should be the place where developers go when they get lost at a lower layer,
it should build confidence in your solution to the problem your API solves.
It should make your solutions obvious, visually and conceptually.
For these reasons, your UI should be stable but nimble, always ready to change as
your API provides new features.

Any REST design will include some operations (such as defining
many-to-many mappings) that can become tedious to work with via pure HTTP requests.
(An example at Stormpath could be mapping an Application to one or more Account Stores – either Groups or Directories in our case). These types of operations should get special attention in your UI as they’re most likely a cornerstone
of understanding your product, and the UI is essential to their clarity.

As we designed our new UI, we tested it heavily with existing and
potential customers to ensure we were accurately conveying the key concepts
in our product.

What We Fixed

We were hungry to re-write our UI: its the most visible piece of our product
and creates an early impression with our customers. But it wasn’t just
aesthetics that bothered us.

In the spirit of lean, our previous user-interface was written in
Vaadin because our team is made up of Java experts. This got us through the first few
phases of our product, as we refined the API and leanred more clearly how customers used it.

The problem with Vaadin is how it became oddly coupled with our business code.
As an API service our number one priority is to place all of the logic and
assertions into a RESTful API that uses predictable conventions and makes sense as you consume
it. By using Vaadin to power the UI we started cheating: rather than using our
public API we started using internal interfaces for manipulating data.

This introduced behaviors and configurations in the product that aren’t exposed in the API and could be confusing for customers.

What We Wanted & Why Angular Won

In planning the new UI, we considered Angular, Ember, and React, as well as SenchaJS. Our choice was driven by clear architecture imperatives.

We wanted to decouple front-end and back-end development

We’re all about speed and it doesn’t sense for our API team to jump out
of Cassandra data modeling to start writing front-end code. We wanted
front-end development to continue independently of backend API development.
To do this we hired a dedicated front-end engineer (that’s me!) and created
a separate codebase for the UI project. When starting from scratch you’ll want
some guidance, and we found that the Angular community had developed some great
project tooling with Yeoman and Grunt.

We wanted our UI to be a Single-Page-App (SPA)**

This is about performance. Think of Gmail and other applications that load once
and then “just work” as you use them, without page reloads.
SPAs typically leverage RESTFul APIs to fetch the user’s data, making this
paradigm a natural fit for us. One of the biggest differences in our new UI is its speed.

We wanted modularity and re-use

Many of our customers were asking for advice
on how to build a UI like ours, with slight modifications. We wanted to build a codebase that could be flexible for customization and Angular is a popular request from our customers.

We didn’t want to incur more technical debt

We wanted confidence that this
application wouldn’t be re-written again after a year. We needed
assurance it would be maintainable and hire-able (how hard will it be
to find engineers who can work on it?). Google has done a very good job of fostering
meetups and being open about the design process for Angular. The result is a
vibrant community that knows how to solve common front-end problems with Angular.

We wanted to continue working with models

Angular does a very good job of
representing your UI as models (via scopes) and this allows you to very easily
decouple the view from the underlying model. In many cases we use our REST models
directly in the Angular application. When looking at Ember and React you will find yourself
working closely with DOM details and not with your data models.

We wanted to re-use as much of our Javascript knowledge as possible

Angular, while opinionated about how to structure it’s components, does not bend the
rules too much with Javascript itself. In fact, we’re using a minimally modified
fork or our Stormpath Node.JS SDK to power the data access layer in our Angular UI.
I compare this to React which suggests (though does not require) you to use
JSX, a compile-to-javascript language.

We wanted it to mesh well with our team dynamic

Front-end web development as
a discipline is changing quickly. Javascript is maturing as a language, and more engineers
want to work with it. In product-minded teams the UI/UX designers are working closely with
engineers – a powerful combination.

Angular fits an interesting sweet spot between skill sets. It gives you the
ability to declaratively define an application from re-usable components.
It ships with some default components, such as ng-show – a simple tool
(called a directive) that hides or shows a piece of the application when a certain
condition changes. You can compose these directives into bigger ones or write
your own from scratch.

This affords a situation where an engineer can create the re-usable
components for your product and a designer can declaratively
compose new application behavior from those pieces. This approach
allows for very effective pair designing sessions.

For an overview of the evolving front-end I suggest reading
A Baseline for Front-End Developers

We Got What We Wanted – What’s Next?

Want to see how this played out? Login to our new admin console at

With this successful release the question becomes: what’s next? Of course
we have a shortlist of bug fixes and improvements, but it’s the big ticket
items I want to share with you. In the coming months we’ll be making
these additions:

Token-Based Authentication

What we built here will also become
available in our SDK’s, allowing you to build your own Angular apps
with token auth!

This oft-requested feature is a big design project for us, both
at the database layer and the UX layer. Stay tuned.

Defining Re-usable Parts

We want to modularize the re-usable
UI components as Angular modules for you to mix and match into your own
Stormpath-backed Angular applications.

Happy New Year!

A friend once said: don’t start the new year without new underwear. Good advice.
As an API provider our undergarments – the API itself – are white and tidy, but we had
an ugly sweater problem. With the help of Angular and our amazing designer, Julie Cheung,
we’re quite dapper now.