Most Single Page Applications (SPA) written in HTML and JavaScript interact with server side code using the familar XMLHttpRequest object. During development it can be convenient to run the application with mock data that eliminates this server dependency. This can be useful if the server side stack is complex and not easy to set up on a local machine or if a shared dev server running the server components suddenly goes offline. It's also handy for tweaking the data returned by the services to ensure the UI behaves appropriately in specific scenarios. Naturally it's imperative to integrate the SPA with real server code early and often but the flexibility provided by the "server mock" technique can be indispensible.

Note: while this article will illustrate how to mock services in an AngularJS application, this pattern applies to any UI technology (JavaScript or otherwise). The key is achieving Separation of Concerns (SoC) that allows real services and mock services to be easily swapped.

Update 12 September 2013: some folks have inquired why I didn't use RESTangular in this blog. I think RESTangular is a fine framework that is more flexible than Angular's $resource abstraction. However, for simple sample code it makes more sense to use $http since more folks are familiar with it. Also, the question misses the main point of this blog post which is applying a pattern so data access code is abstracted, thereby simplifying the controller code. If your application grows and requires new code to implement custom caching or request queueing logic, the Repository will be the perfect place to do it. You can apply this pattern with $http, $resource, RESTangular or any other data access framework. And that's the whole point: by abstracting the data access code, the controller doesn't care how data is fetched; it only expects a promise to be returned which will later be resolved or rejected.

Let's get started!

The Old Way: Use $http Directly

Angular provides the $http and $resource "services" for making HTTP calls to load data into your app. In tutorials and simple applications these are frequently injected directly into UI controllers:

Here the controller invokes $http directly and asks it to fetch data from a known URL. The same approach works for $resource as well. While this approach is simple, it offers limited flexiblity and begins to overcomplicate the controller when data access becomes nontrivial.

Assume we have a number of UI widgets on this page that control the type of donuts we wish to load. When we invoke the backend service, we need to pass parameters to filter the donut based on size, filling, glaze and presence of a hole:

The code to construct the URL is getting more complex and muddying up the controller a bit. Furthermore if we have other views that need to fetch these donuts this code would need to duplicated. Clearly we can improve the design through some refactoring and application of patterns.

The New Way: Use a Repository

This technique involves adding an intermediate layer between the controller and $http that encapsulates data access and simplifies the code in the controller. Here's a simple example of this expressed as an Angular module:

Note: I'm calling this intermediate a "Repository" although other terminology is likely valid, based on your preference. See "Quick Note on Names" below.

The Repository provides a very similar API as $http in that it ultimately returns a Promise that is later resolved with the data returned by the server. However, it exposes a set of methods which provide a cleaner API to the controller than forcing it to perform string concatenation to build up URLs that are passed to $http.

Using a Repository to Swap Out Mocks and Real Services

Now let's explore how we can easily swap out real and mock services with another simple Angular module example:

Now we have a new "mock" implementation that loads a JSON file from the local web server. We use Angular's factory method to control exactly what object is bound as donutRepository for injection into the controller. Alternatively the mock implementation could simply create its own data programmatically and return a promise using the $q and deferred APIs:

The configModel referenced by the factory above is a simple object that holds configuration information about the application. The implementation below allows us to control the config options by passing parameters via the URL to the AngularJS app on startup:

Accessing the application via http://some.url/index.html#?useMocks=true will enable mock mode, based on the code above.

Once we push all data access code into its own discrete layer we can derive other benefits as well. We can easily centralize cross-cutting concerns such as logging or caching into our repository layer. If we need to implement offline mode in an application, each repository can collaborate with a service that queues up requests and pushes them to $http once the application comes back online. This is vastly preferrable to managing this complexity in a controller.

Sample Application

I've built a very basic "Reddit Browser" AngularJS application that provides a working sample of these techniques. The code is available on Github here:
"blog-examples" repository

Clone the repo and then start the Node web server script using: ./scripts/web-server.js

The app will be available here:
http://localhost:8000/ng-repository/src/index.html

"Mock mode" can be run easily via hitting dev.html instead.

Feedback is encouraged. Drop me a comment below, use my contact form or hit me up on Twitter.

A Quick Note on Names

I pushed this section to the end because it's just dealing with semantics. I chose "Repository" as the term for the the new data access layer but there are a variety of terms that are sensible. At the end of the day, the name has significance but the application of the pattern is what really matters. Here are a few other options:

Proxy: because the intermediate sits between the client controller code and (ultimately) the backend server hosting the service. However, "Proxy" is an extremely generic pattern and doesn't really tell us what it's acting as a proxy to.

Service: due to the popularity of the Service Oriented Architecture (SOA) buzzword, components residing on a server that return data in a HTTP response are frequently called "Services." Therefore we could call the intermediate a Service. However, in the context of an AngularJS application this would be confusing since "service" is used generically to describe virtually any object available for dependency injection in the AngularJS context.

Repository: made popular in Eric Evans' book entitled Domain-Driven Design: Tackling Complexity in the Heart of Software, a Repository can be used in server side code to encapsulate querying and persistence, ultimately returning one or more Domain Objects. This aligns pretty closely with what's going on in the AngularJS app so I decided to go with it.

Data Access Object (DAO): this one is popular in Java circles. It's probably at least as valid as Repository, perhaps moreso since it doesn't carry along the Domain Model connotations.

Many developers struggle with how to organize an application's code base once it grows in size. I've seen this recently in AngularJS and JavaScript applications but historically it's been a problem across all technologies including many Java and Flex apps I've worked on in the past.

The general trend is an obsession with organizing things by type. It bears a striking resemblance to the way people organize their clothing.

Piles on the Floor

Let's take a look at angular-seed, the official starting point for AngularJS apps. The "app" directory contains the following structure:

css/

img/

js/

app.js

controllers.js

directives.js

filters.js

services.js

lib/

partials/

The JavaScript directory has one file for every type of object we write. This is much like organizing your clothes into different piles on the floor. You have a pile of socks, underwear, shirts, pants, etc. You know your black wool socks are in that pile in the corner but it's going to take a while to dig them out.

This is a mess. People shouldn't live like this and developers shouldn't code like this. Once you get beyond a half-dozen or so controllers or services these files become unwieldy: objects you're looking for are hard to find, file changesets in source control become opaque, etc.

The Sock Drawer

The next logical pass at organizing JavaScript involves creating a directory for some of the archetypes and splitting objects into their own files. To continue the clothing metaphor, we've now invested in a nice mohaghony dresser and plan to put socks in one drawer, underwear in another, and neatly fold our pants and shirts in still others.

Let's imagine we're building a simple e-commerce site with a login flow, product catalog and shopping cart UI's. We've also defined new archetypes for Models (business logic and state) and Services (proxies to HTTP/JSON endpoints) rather than lumping them into Angular's single "service" archetype. Our JavaScript directory can now look like this:

controllers/

LoginController.js

RegistrationController.js

ProductDetailController.js

SearchResultsController.js

directives.js

filters.js

models/

CartModel.js

ProductModel.js

SearchResultsModel.js

UserModel.js

services/

CartService.js

UserService.js

ProductService.js

Nice! Objects can now be located easily by browsing the file tree or using IDE shortcuts, changesets in source control now clearly indicate what was modified, etc. This is a major improvement but still suffers from some limitations.

Imagine you're at the office and realize you need a few outfits dry-cleaned for a business trip tomorrow morning. You call home and ask your significant other to take your black charcoal and blue pinstripe suits to the cleaners. And don't forget the grey shirt with the black paisley tie and the white shirt with the solid yellow tie. Imagine that your significant other is completely unfamiliar with the your dresser and wardrobe. As they sift through your tie drawer they see three yellow ties. Which one to pick?

Wouldn't it be nice if your clothing was organized by outfit? While there are practical constraints like cost and space that make this difficult with clothing in the real world, something similar can be done with code at zero cost.

Modularity

Hopefully the trite metaphors haven't been too tedious but here's the recap:

Your significant other is the new developer on the team who's been asked to fix a bug on one of the many screens in your app.

The developer sifts through the directory structure and sees all the controllers, models and services neatly organized. Unfortunately it tells him/her nothing about which objects are related or have dependencies on one another.

If at some point the developer wants to reuse some of the code, they need to collect files from a bunch of different folders and will invariably forget code from another folder somewhere else.

Believe it or not, you rarely have a need to reuse all of the controllers from the e-commerce app in the new reporting app you're building. You may however have a need to reuse some of the authentication logic. Wouldn't it be nice if that was all in one place? Let's reorganize the app based on functional areas:

cart/

CartModel.js

CartService.js

common/

directives.js

filters.js

product/

search/

SearchResultsController.js

SearchResultsModel.js

ProductDetailController.js

ProductModel.js

ProductService.js

user/

LoginController.js

RegistrationController.js

UserModel.js

UserService.js

Any random developer can now open the top-level folder and immediately gain insight into what the application does. Objects in the same folder have a relationship and some will have dependencies on others. Understanding how the login and registration process work is as easy as browsing the files in that folder. Primitive reuse via copy/paste can at least be accomplished by copying the folder into another project.

With AngularJS we can take this a step further and create a module of this related code:

If we then place UserModule.js into the user folder it becomes a "manifest" of the objects used in that module. This would also be a reasonable place to add some loader directives for RequireJS or Browserify.

Tips for Common Code

Every application has common code that is used by many modules. We just need a place for it which can be a folder named "common" or "shared" or whatever you like. In really big applications there tends to be a lot of overlap of functionality and cross-cutting concerns. This can be made manageable through a few techniques:

If your module's objects require direct access to several "common" objects, write one or more Facades for them. This can help reduce the number of collaborators for each object since having too many collaborators is typically a code smell.

If your "common" module becomes large subdivide it into submodules that address a particular functional area or concern. Ensure your application modules use only the "common" modules they need. This is a variant of the "Interface segregation principle" from SOLID.

Add utility methods onto $rootScope so they can be used by child scopes. This can help prevent having to wire the same dependency (such as "PermissionsModel") into every controller in the application. Note that this should be done sparingly to avoid cluttering up the global scope and making dependencies non-obvious.

Use events to decouple two components that don't require an explicit reference to one another. AngularJS makes this possible via the $emit, $broadcast and $on methods on the Scope object. A controller can fire an event to perform some action and then receive a notification that the action completed.

Quick Note on Assets and Tests

I think there's more room for flexibility with respect to organizing HTML, CSS and images. Placing them in an "assets" subfolder of the module probably strikes the best balance between encapsulating the module's asset dependencies and not cluttering things up too much. However I think a separate top-level folder for this content which contains a folder structure that mirrors the app's package structure is reasonable too. I think it works well for tests as well.

A colleague of mine recently recommended the i18n-js library for internationalization. i18n-js is a lightweight library (~700 lines) which implements string lookup and formatting and is a suitable replacement for Angular's localization libraries.

I've written a proof-of-concept showing how the two can be integrated and made the source available at Github. Below is an explanation of some of the key files. Some of the gists have been trimmed slightly to ease formatting on the page, so refer to Github for the full code.

The above adapter wraps the core i18n-js APIs and makes it easy to load message bundles for a given locale. I wanted this functionality to stand on its own, so note that there is no dependency on AngularJS itself in this file.

The code above goes in the root HTML page and is used to load the message bundles for the default locale and then bootstrap the Angular application. This ensures all bundles are finished loading before the Angular application inits. This can be important if some application modules require the translations or formatters to be ready during initialization.

The above snippet exposes the i18n-js functionality via a few straightforward AngularJS filters. If other application components require access ot the I18nAdapter itself, it would be easy to add a service or factory here to make the adapter injectable.

If you clone the Github repo and run it under a web server, you can see a very simple AngularJS app making use of this code. Enjoy!

The other day I threw together a quick proof-of-concept for integrating AngularJS with the jQuery Globalize Plugin. The first part is a simple utility Angular "service" which loads the appropriate JSON message bundle: