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

https://api.stormpath.com

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!

Custom Data Search

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.