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.
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.