Category Archives: Architecture

GIDS 2014

A couple of weeks ago, I had the privilege of speaking at GIDS (the Great Indian Developer Summit) 2014 in Bangalore. GIDS is a multi-day event, with each day dedicated to a particular theme or topic. I spoke on the Wednesday (the Web/Mobile day) and had three sessions covering mobile app development using iBeacons, tips and tricks using AngularJS, and automated Web testing using JavaScript.

Thanks to everyone who came to each of the sessions. I really enjoyed the feedback and audience participation, and look forward to similar sessions in the future. I’ve included links to the three decks below on Slideshare, and have posted all of the source code here.

Automated Web Testing using JavaScript

The process of creating automated tests for Web applications has been around for many years. Vendors such as HP, Parasoft, QFS, and even Microsoft have test software that can be used to create and run automated tests. Over the past couple of years however, we’ve seen an industry-trend towards open source Web testing solutions based on JavaScript. Such solutions have the advantage of being easily modified, free to download, very modular, supported by a vibrant community, and (given the popularity of client-side JavaScript) tests can often be written using the same language as the Web application. 

For this blog post, I wanted to share some of our observations at Neudesic, and some of the tools that we’ve had success with during recent projects.

Unit Tests or Assertions?

Before considering any unit test, one of the questions we try to ask is whether the same functionality can be provided by an assertion. An assertion is, in its simplest form, code in your application that asserts that some condition is true – and if it’s false, stops the application and/or reports an error message.

The easiest way to perform an assertion in JavaScript is with the console.assert function. This is supported on the latest version of most major browsers (Chrome, Safari, and IE 10 upwards). A simple use of console.assert might look as follows:

var myMethod = function(x){
  console.assert(x, 'X should not be undefined');
  /* rest of method goes here */

As shown above, this is the simplest form of an assertion, yet quite effective. More importantly, it also negates the need to have a redundant unit test that checks whether the value of x is null, resulting in fewer tests that simply do assertion checking. There are many developers who use assertions during development and then strip out the assertions for production. While this has some merit, a more productive approach can be to create your own assertion function. This might look something like the following:

var myMethod = function(x){
  assert(x, 'X should not be undefined');
  /* rest of method goes here */

As shown above, instead of calling console.assert we call a custom function. This has the advantage that in development mode we can inject an assert function that writes to the console or adds a breakpoint in code, whereas in production mode we might choose to display a more friendly error message to the user and potentially log the crash via an analytics service.


Assertions are useful for performing simple checks on methods, but there will likely come a time where you need to perform more rigorous tests of logic, using a unit test. QUnit is a popular JavaScript framework for unit testing, whose origins come from jQuery and jQuery UI. QUnit works by defining a set of tests that are run within the QUnit test runner (which itself is just a Web page). Unit tests are simple, and follow a format similar to the following:

test('a basic test example', function() {
  var value = 'hello';
  equal(value, ‘hello', 'We expect value to be hello');

If you are new to unit testing in JavaScript, and starting out by writing simple single page tests, QUnit is a good way to get started.

Jasmine and Karma

While QUnit provides a good introduction to unit testing, it is easy to quickly reach a limit, especially if your application has a lot of tests nested in a hierarchy. In addition, QUnit does not typically provide any CI (Continuous Integration) functionality out of the box. As you increase your familiarity with unit testing using JavaScript, it is well worth checking out Jasmine and Karma.

Jasmine is a BDD-style framework for writing tests. While similar to the QUnit construct, the syntax tends to be cleaner and more widely adopted in the JavaScript community:

describe('a basic test example', function() {
  it('tests that true is always the truth', function() {

As can be shown in the example above, the describe, it, and expect keywords work with unit tests, but also apply to BDD style tests also – making Jasmine a good candidate for writing tests of both types. Jasmine is just a language syntax and by design doesn’t offer any test runner implementation. Fortunately, there are a number of test runners available that can run Jasmine tests. One such framework gaining adoption is Karma, a test framework developed by the AngularJS team at Google.

Karma, which used to be called Testacular (insert your joke here about why the name changed!), is a flexible test framework that can be used to call unit tests written in Jasmine and other frameworks. Karma is very lightweight, which means it works well in CI (Continuous Integration) settings, even to the point where it’s possible to have Karma invoke a series of tests after each file save on your development machine. While there are many different test runners capable of executing unit tests, I believe Karma adoption will continue to grow, and this should be something that you should look at for your own testing needs.


Unit testing is useful for testing discreet logic in your application, but falls short of telling you whether the application is working correctly for the user in their environment – i.e. through their browser. To do this we need to turn to integration testing – testing the end to end operation of your Web application. Selenium is an open source project that has been in development for the past 10 years, originally developed by ThoughtWorks as a replacement for Mercurial (hence the name, as Selenium is often used to cure Mercury poisoning!).

Today, Selenium has three major components: Selenium IDE, Selenium WebDriver, and Selenium Grid.

Selenium IDE is a browser extension for Firefox that enables you to record a series of actions and test assertions via a “recording function” in the browser. By default, the test gets written to a HTML-based test suite, and can be replayed at any time. While Selenium IDE is a useful tool for investigating the underlying operations of the testing platform, it is not well suited for use in production – the tests don’t support inheritance, which makes management of the tests difficult, especially when things change in your application. Moreover, the tests have to be run through the Firefox browser, which makes true automation difficult.

Selenium WebDriver (which used to be Selenium RC) is a server-side version of the Selenium testing platform that does support scripted tests. WebDriver (based on the emerging WebDriver spec, hence the name), runs as a Java service and accepts incoming TCP socket connections from test clients. Upon receiving a connection, the service invokes a browser, runs the tests, and reports status back to the client via the socket. Any test platform that implements the WebDriver specification can issue tests to a Selenium server.

Selenium Grid is a service where multiple Selenium servers can be clustered to handle a high volume of tests. It is often used by service providers (such as SauceLabs) who are offering testing services to multiple clients.

For many projects, Selenium WebDriver makes the most sense. In order to use WebDriver with Jasmine however, you still need to have a test runner (remember that Jasmine doesn’t provide any test platform). Karma is not a fit here as it is best suited for unit tests, not end-to-end tests (as it happens, the documentation actually discourages the use of Karma for integration testing). To solve this, we turn to another testing framework from Google, Protractor:

Protractor is an end-to-end test framework, typically used to test AngularJS applications – although any Web application can be tested as protractor contains methods to call the underlying WebDriver implementation. It is built upon a library called WebDriverJS, a JavaScript-implementation of the WebDriver client, which makes it wire compatible with Selenium WebDriver. Protractor is simple to install, and supports Jasmine as it’s primary test language. A test using protractor might look as follows:

describe('test hello world home page', function() {
  it('should greet the named user', function() {
    var greeting = element(by.binding('yourName'));
    expect(greeting.getText()).toEqual('Hello Simon!');

As you can see above, this simple test will open a Web page, look for a data binding called ‘yourName’, send a name to it, and then assert that the greeting replied is correct. You should note that the model and binding above are specific to AngularJS, and (if you are not using AngularJS) can be replaced with similar lookups based on HTML ID, CSS, or XPATH query. Using the protractor test runner, this test can be sent to an instance of Selenium, which in turn will invoke a new browser, run the test, and report back the results to the client.

IDEs for Creating Protractor Tests. While creating tests is a manual process today, there are several open source projects with a goal of being able to generate protractor-based tests from a more visual interface. One such tool is Selenium Builder, which while still in Alpha, looks very promising.

Using Page Objects. While Jasmine and Protractor offer a very quick way of creating and running tests, you often need to be careful to manage the tests that you create. If you make a simple change in the UI, you want to avoid a situation where you need to change many tests. One way of overcoming this is to use Page Objects when using Protractor. A Page Object is, by definition, a JavaScript class that defines methods on a page.

These methods might be AddCustomer, DeleteCustomer, ModifyCustomer, etc. The tests then call these page objects to perform the function. For example, AddCustomer(valid), AddCustomer(invalid), AddCustomer(invalid2), etc. This approach offers many advantages, especially if the page changes. If a change to page occurs, only the page object has to be changed once, which makes maintenance and re-use throughout the tests more predictable.

PhantomJS. Finally, as we discussed previously, Selenium works by invoking a new browser process in order to run tests. While this is useful on your development machine, there are times where you may want to invoke tests that do not have access to a fully installed browser – for example, if you are doing server-side tests on a Linux or a Docker instance without a UI installed. To accomplish this, PhantomJS can be used. PhantomJS is a headless version of WebKit written in Qt, and can act as a browser without any of the UI overhead associated with actually launching a browser.

PhantomJS can be invoked in one of two ways – either plugged directly into Selenium as an alternative browser process – or, because PhantomJS implements GhostDriver (wire level compatibility with WebDriver), it can be called directly from Protractor. PhantomJS is still in early development stages (and at the time of writing being ported to Qt5), but looks to offer a lot of potential for developers who are looking to do integration testing in a headless environment.

iBeacon Demo at Gartner AADI

Last week, I joined my colleagues from Neudesic at the Gartner AADI (Application Architecture Development & Integration) Summit in Las Vegas. One of the neat things that we were showing was a demo of iBeacon technology, in order to help locate and pinpoint individuals within indoor environments where GPS is not an option. 

To achieve this, we placed a selection of iBeacons around the expo floor (for the iBeacons we used RedBear’s BLE Mini boards, flashed with their iBeacon firmware).

Red Bear BLE Mini

Using Bluetooth LE (a.k.a. Bluetooth Smart), each beacon transmits a unique ID (made up of a major and minor value) on a particular “frequency” (known as a proximity UUID). iBeacon supported mobile applications are then able to “tune in” to this proximity UUID, and based on the power signal for each beacon, determine which area of the floor a user is located closest to.


Gartner AADI screenshot

Using this information we created a mobile app that reports on all of the beacons within range on the expo floor. As you can see in the above screenshot, we have 5 iBeacons in range, listed in order of proximity, with an estimated distance calculated by the power signal. As you can likely gather from the data, we were located in the Neudesic booth at the time this screenshot was taken, with the theater, and a selection of other booths in range.

For the show, we developed two versions of the application – one for iOS and one for Android. Both are native mobile applications written using Xamarin, using CLLocationManager for iOS, and Radius Network’s binding for supporting iBeacon on Android. The Radius implementation is especially interesting in that the beacon detection runs as a background service, polling for new iBeacons and raising intents to the UI as necessary (even though Bluetooth LE is a lot more responsible with power vs. regular Bluetooth, we still need to be careful not to kill the battery when using this however).

While this is neat to show just as a mobile application, we wanted to take it one step further and demonstrate how this could be applied in the real world with Neuron, an ESB product from Neudesic. For our expo demo, Neuron provided a backbone infrastructure to allow the mobile app to resolve a name for a beacon ID (think of his like DNS for iBeacons!) and also give a scalable way for users to “check in” to an iBeacon the same way that they would check in via Foursquare or Facebook.

Neuron process flow

As shown above, we developed a process flow using Neuron to accept incoming messages from the mobile application, and then provided logic to determine whether the device was trying to acquire a name for a beacon, or whether the user had walked in to the area of a beacon and wanted to “check in”. The benefit for using Neuron in this situation vs. just propping up a single web service is that our application can now scale to hundreds of thousands of concurrent mobile clients without needing to make any major adjustments on the server-side.

If you were able to stop by the booth at the Gartner summit, I hope you enjoyed the demo and the conversation. If you weren’t able to attend, but would like to know more about how Neudesic is working with various organizations on iBeacon technology and/or Neuron, feel free to drop me a line.

Building a WebRTC Client for Android

*** Update:  As a few readers have pointed out, the libjingle source has now been merged into the main WebRTC branch ( As a result, some of the instructions here will need to be adjusted.  I’m going to leave the post as is, but bear this in mind if you are following each of the steps.  Thanks.  ***

If you’ve been following any of the recent developments with WebRTC, you’ll know that the majority of samples and example code available today target the Web browser (typically Chrome or Firefox).  While this is useful to get up to speed, IMO one of the most powerful applications of WebRTC will be for mobile devices.  Despite this, getting WebRTC running on mobile can be somewhat challenging.

While Chrome Beta for Android supports WebRTC, any true mobile client will always need some kind of native application (in order to receive incoming calls in the background).  In this post, I’ll be showing how to walk through the minefield of compiling WebRTC for Android in order to build your own demo app that you can expand upon.


Configuring your Build Environment

In order to build Android WebRTC, you are going to need a machine running Linux.  For the purposes of this article, I would recommend some kind of virtual image (VMWare or VirtualBox) running Ubuntu Server 12.04.2 LTS.  When you build your VM image, ensure that you use the 64bit version of Ubuntu, and that you allocate a minimum of 2Gb RAM to the image (any less and you may well see the compiler running out of memory).

After you get your Linux VM up, the first thing is to install the required build tools.  First, the git and subversion clients:

sudo apt-get install git git-svn subversion

Then, you’ll need the Chromium depot tools – these tools are required to build the WebRTC bits, much of which derives from various parts of the Chromium project.  To install:

cd ~
git clone

After the tools have been brought down, you’ll also need to add them to your path:

echo export PATH="$PATH":`pwd`/depot_tools >> ~/.bashrc

Once this is done, log out and log back in to the server.  From the command line run:


If all is working, you should see a list of available client commands.  If you see “command not found”, edit the ~/.bashrc file and double check your path is set correctly.

The final part of configuring your build environment involves installing some required libraries and compilers.  To perform this, use the following command:

sudo apt-get install g++ pkg-config gtk+-2.0 libnss3-dev

Once this is complete your machine should be in a position to start pulling down the WebRTC code.

Obtaining libjingle Source Code

In order to build the Android WebRTC client, we are going to pull down and compile the “libjingle” project.  Libjingle is a set of components to interoperate with Google Talk, but also contains (at the time of writing) the most complete and functional Android client.

To pull down the source, follow these instructions:

cd ~
mkdir libjingle
cd libjingle
gclient config

After you’ve run the config command you should notice a new file called .gclient in the ~/libjingle directory.  Edit this file (using VIM or nano) and append the following to the end of the file:


This will instruct gclient to pull down the required third party libraries and other tools for an Android build of libjingle.

With this file modified, run the following command from the ~/linjingle directory:

gclient sync --nohooks

This will start a large sync of the liblibjingle source code, which will likely take some time.  A great opportunity for a coffee or break at this point!

Installing the Oracle JDK

Before we can compile libjingle, we’ll need to install the Oracle JDK.  Although the majority of the library is native (and uses the Android NDK) this is required to build the JAR and APK file at the end of the build.

To install, go to the Oracle JDK downloads page ( and download the latest JDK 1.6.  Note that JDK 7 will not work and you will get errors later on.  For the purpose of this tutorial I have been using Java SE Development Kit 6u45.

As you are running server, you may need to download the JDK on another machine (where you will need to accept the license agreement) and then copy the .bin file to your Linux server (using either curl, wget, or VMWare shared folders).

Assuming the .bin file is in your home (~) directory, to install the JDK, perform the following:

cd /usr/lib/jvm && sudo /bin/sh ~/jdk-6u45-linux-x64.bin -noregister

This will extract the JDK to the /usr/lib/jvm directory.  After this is complete, we need to set the defaults to use the Oracle VM as opposed to the OpenJDK VM (which is installed by default).

sudo update-alternatives --install /usr/bin/javac javac /usr/lib/jvm/jdk1.6.0_45/bin/javac 50000
sudo update-alternatives --install /usr/bin/java java /usr/lib/jvm/jdk1.6.0_45/bin/java 50000
sudo update-alternatives --config javac
sudo update-alternatives --config java

Finally, to overcome a small bug in the libjingle gwp compile scripts, we need to create a symbolic link:

cd /usr/lib
ln -s jdk1.6.0_45 java-6-sun

After you’ve done this, run the following command:

java -version

If you see “Java HotSpot build 1.6.0_45″ instead of “OpenJDK”, the correct version of Java is install and you should be in good shape.

Preparing for Compilation

Before we compile, there are a few things that are required.  Firstly, we need to install some 32 bit compatibility libraries so that aapt and other Android compilation tools will function correctly.  To install, run the following command:

sudo apt-get install ia32-libs

Next, edit ~/libjingle/trunk/third_party/webrtc/build/common.gypi

Navigate to the line that contains:


and replace with:


This will prevent the Android client from crashing (when it realizes it doesn’t have a default trace file) and will make debugging the Android application a whole lot easier!

Finally, perform the following commands to complete preparation:

cd ~/libjingle/trunk
. ./build/android/

This will correctly setup the android dependencies.  Note the leading period on the envsetup script – this is very important as we need the variables to be set for the rest of the session.

Assuming these commands ran without errors, now run:

gclient runhooks

This command will generate the required ninja gwp compilation scripts.  After this, run:


You may get an error indicating that content.gyp could not be found – it is fine to ignore this for now.


If you’ve reached this stage, congratulations!  We can now try to compile!  To do this, run the following command from the ~/libjingle/trunk directory:

ninja -C out/Debug -j 10 AppRTCDemo

This command is instructing the ninja compile tool to generate a debug version of the build, using a maximum of 10 concurrent build threads.

Depending on your machine, compilation will likely take about 10-15 minutes (time for that other coffee!).  Assuming everything went well, you should see some output in the ~/libjingle/trunk/out/Debug folder:


This is the main demo APK.


This is the JAR for libjingle.

This is the ARM-based native library.

Running the APK on your device

To run the APK on your device, copy the file to a machine with ADB installed (and your device connected) and run the following command:

adb -d install AppRTCDemo-debug.apk

If all goes well, you should see a new application called “AppRTC”.  To test the application, launch a new browser on your desktop (not on the phone!) and navigate to  Enable access to your camera and microphone and note the room number of the conference window.

Now, launch the AppRTC application on your device and enter the room number as part of the URL (ensure that there are no spaces).  If all goes well you should have an established connection with video and audio between the browser and the mobile device!

If you run into issues (and this is quite complex, so it’s usual) check ADB logcat for any errors and exceptions that are being produced by the AppRTC application.  Although functionally, this code is working, at the time of writing the TURN server being hosted on Google’s Compute Cloud is having some issues – so I had to dive into the code and configure the application to use an alternative – but that’s probably a good excuse for another post sometime in the future!

Either way, I hope this was useful and good luck!

Designing a Web API for Mobile Apps

At Neudesic, almost every mobile project that we’ve been involved in has had some dependency on a Web API.  This has included APIs that we’ve had to create from scratch, as well as ones that already exist that the app has to consume.

As you can imagine, over the past few years, we’ve seen a fair share of good and bad API design.  In this blog post, I wanted to share some of my observations, thoughts, and questions that I ask of a well designed Web API, especially one that will be called from a mobile app.

1.  Are the basics being met?

First, the basics.  Without question, every Web API should be stateless.  There should be no session state, cookies, or server-side values used to hold any state of any kind.  Adding state adds complexity, and limits the ability for the API to scale, which for a mobile application that could reach millions of users is something that we want to avoid.

Also, endpoints of the API should be exposed through SSL by default.  SSL is easy to setup, performant, and should be enabled for any API that we either consume or create.  As you may have observed, using SSL as default seems to be a direction in which many other APIs are heading.

2.  How do we authenticate with the API?

Authentication is critical to a Web API, and (in my opinion) is one of the common pitfalls.  As a rule, user credentials should never be passed as part an API call.  Take the following example:

GET /accounts?username=simon&password=simon

Doing this is bad for three reasons:

Firstly, although the URL gets encapsulated as part of the HTTPS session, it is likely still visible in any logs on the Web server.  This often also applies to user credentials passed as HTTP headers.

Secondly, it makes debugging with users and other developers awkward (because you often need to ask for their username and password).  This is especially bad if the credentials are corporate accounts used for other systems.

Finally, and most importantly, these types of credentials typically have a long shelf life.  If the call is ever compromised, there’s a good chance that it can be replayed back to the service up until the password is changed, which could be many months (if ever at all).

To overcome this, some APIs use an application key or some other token derived from a HMAC algorithm.  This may work for some scenarios, but unfortunately if the key is exposed, it can be difficult to revoke.  This is especially true if the key has been embedded in a mobile app running on thousands of devices.

Fortunately, to overcome both of these issues, there is OAuth 2.0.  OAuth 2.0 works by having the user pass a set of credentials (typically a username and password) to an authentication service.  Assuming the credentials are valid, the user/application/consumer receives back an access token.  This access token is then passed as a HTTP Authorization Header to the Web API to verify the authenticity of the request.  Moreover, this access token has an expiry (I find an hour to be a good time frame) so that if someone were to get hold of the token, their usage of the API is limited to this timeframe.  (You can read up much more about OAuth 2.0 here)

There’s no doubt that implementing OAuth 2.0 involves more work, including setting up an authentication API and handing the lifetime of the token, but the end result is an API that is more secure and will also reflect the security model used by many others (e.g. Facebook, Google) – which means that you can even use these third parties as identity providers if you so choose.

3.  Is the API really using REST?

I’ve seen many examples of people thinking that they have a REST API when really they don’t.  Correct use of REST is about nouns, not verbs.  Let’s take this URL for example:

GET /GetAccountBalance?account_id=1234

Although the above URL is accessed over HTTP, it’s really not a REST API.

Using REST to it’s true intention means combining HTTP VERBS together with nouns or entities in the URL that represent the data you are exposing.  Instead of the previous URL, a correct REST syntax would be the following:

GET /accounts/1234

To create a new account we would use a HTTP PUT (together with a payload with the new account information)

PUT /accounts

To delete an account, we would use:

DELETE /accounts/1234

This noun-based approach can also work with hierarchical data.  For example:

GET /accounts/1234/transactions/50

Will return the a transaction (with id of 50) for Account 1234.

Overall, a good understanding of REST, together with a focus on exposing nouns instead of functional methods will go a long way to create a more more usable and accepted API.

4. How should we consume this API?

If you are dealing with an API that exposes a lot of entities, in addition to exposing generic REST endpoints, there are typically six things also worth considering:  Sorting, Searching, Filtering, Pagination, Helpers, and Partial Responses.

Sorting.  Should the API return a sorted list of data to the consumer/application?  If so, a sort parameter on the noun can be useful:

GET /accounts?sort=id

GET /accounts?sort=-id

As shown above, a leading hyphen to indicate ascending or descending sort order can be a great timesaver (and often negates another query string parameter for sort order).

Searching.  Similar to sorting, providing a way for consumers to search entities can be useful.  The use of the “q” parameter for search is somewhat standard:

GET /api/accounts?q=acme

Filtering.  Another useful pivot for any REST based API is the ability to filter on a particular noun.

GET /accounts?filter=balance%3E500

(You can choose to use the URL encoded character for > as shown above, or I’ve seen many other APIs use gt, lt query parameters).

Pagination.  A type of filtering, especially useful for large datasets.

GET /accounts?limit=50&offset=25

This above call will get the next 50 accounts, starting at the 25th entry.

Helpers.  With many APIs there are a number of common requests.  Maybe it’s the list of top ten customers, or the best sales people of the month. Putting these common requests as “helpers” into the API can be very useful for consumers, and can also help reduce the “chattiness” of the API by reducing the number of repeat requests.

GET /accounts/top-ten

Partial responses.  Finally, many consumers of the API (especially mobile applications) will want only a summary set of data.  This can be useful to build a list of items (in a master/detail view), without having to send the entire details for each item.

GET /accounts?fields=id,name,balance

Of course all of the above parameters can be combined as required.

GET /accounts?fields=id,name&sort=id&limit=100&offset=50

5.   What will the API return?

For the majority of APIs, especially those that will be consumed from a mobile application over a potentially slow connection, returning JSON is always good practice.  Compared to XML, data returned in JSON format will likely be more lightweight, and will require less parsing and processor overhead on the device.

With that said, there are cases where other formats might be required – for example, a legacy system that is already expecting data in XML.  In which case, you might want to consider allowing the consumer to specify what type of data to return either through the HTTP Accept header or through a URL action (useful if you anticipate doing a lot of debugging).

GET /accounts?format=xml

There has also been a lot of talk recently about HATEOAS (Hypermedia As The Engine Of Application State), a term coined by Roy Fielding.  While there are many articles and presentations that explain Roy’s initial intentions, for the purpose of this blog post (and my own sanity), HATEOAS in a Web API referring to the use of links that instruct the consumer where to go for related information.

For example, let’s imagine we made the following API call:

GET /accounts/1234

We might receive the following response:

{ "account_id" : "1234", "balance" : "100.90" }

With a “HATEOAS-compliant” Web API, we may also receive embedded links.  For example:

{ "account_id" : "1234", "balance" : "100.90", { "_links" : { "transactions" : { "href" : "/accounts/1234/transactions" } } } }

As you can see above, the API returns the data for the account, but also returns a link to the API call that will return all of the transactions for that account.  Think of these links as helping the consumer navigate to other related API calls.  (Incidentally there are a number of JSON formats for doing this, although I would recommend JSON HAL

6.  Are the methods of the API consistent? 

While it’s difficult to recommend what you should name your methods and other parts of your API, the key to success is often consistency.  For example, if you have the endpoints for your accounts here:

GET /accounts

For your invoices, it would be silly to have them here:

GET /order_entry/ledger/invoices_full

In an ideal world (and even one without HATEOAS!), a user should be able to guess what the API should be based on previous usage.  Keeping the paths and names consistent are key to making this happen.

Related to this, choosing the right case for APIs can be very important.  Having these two apis:

GET /accounts

GET /Invoices

will likely lead to issues because of the case mismatch on the entity name.  My recommendation is to use lowercase throughout (then there is no ambiguity) and to use snake case to conjoin words.  For example:

GET /customer_details

Spinal case (using hyphens) is also acceptable, but if you are doing a lot of descending sorting, you may want to be careful.

Finally, in terms of consistency, it’s always nice to be consistent with pluralization:

GET /accounts/1234/invoice

Assuming there are more than one invoice per account, this could also run people into trouble.  I would recommend deferring everything to plural to ensure consistency.

GET /accounts/1234/invoices

7.  How is the API versioned?

Versioning is important, especially if there are breaking changes in production environments.  There are a couple of ways to achieve this:

For large volume APIs where version consistency is critical, I would recommend placing the version information as part of the API call.

GET /v1.0.0/accounts

Versioning by using the URL makes it very explicit as to the version that the consumer is using.

For less critical systems, or for APIs where breaking changes are going to be rare, I would recommend that consumers pass an optional version number as part of the HTTP header.  If the version number is passed as part of the post, the consumer gets a specific versioned response, otherwise they’ll be receiving the latest version.

In addition to version numbers, I always like to see specific environments affiliated with the URL.  This is most easily done as part of the host subdomain, as it will likely correspond with the physical or virtual machine that the API is hosted from:




The above makes it very clear whether I’m hitting the development, UAT, or production version of the APIs when I make my calls.

8.  How is the API documented?

If you have a well designed API, you do not need to spend hours of time documenting the API in a Word document.  If anything you are going to end up with a Word document that will become quickly out of date.  In terms of documentation, there are two things that I find invaluable:

Firstly, mandatory and optional methods and parameters should be documented.  It’s important that consumers understand what they can and cannot pass to the API.  What’s nice is that this documentation can typically be auto generated from the method signatures or comment blocks (which will keep your documentation in sync with your code).

Secondly, sample code to show how to call the API.  A few sample calls for each method can be a life saver and much more valuable than reams of documents.  In these samples, show how the request should be formatted and what the response looks like.

9.  What does the API return when things go wrong?

Returning useful error messages to consumers of your API is really important.  You should think about two types of error messages – ones that can be expressed with HTTP result codes, and ones that cannot.

For the ones that can be expressed through a result code, simply return the result code with an optional body of information (in JSON format).  For example, if the access token has expired, return a 401 HTTP error code, and maybe some JSON payload to help debugging.  Also, if any part of the system is down (e.g. the database connection can’t be established), I would recommend returning a 500 for clarity.  With any HTTP result code, remember to pass the right one.  A good rule of thumb is that result codes in the 400′s typically indicate an error with the client, whereas codes in the 500′s means that something has gone wrong on the server.

For errors that can’t be expressed through a HTTP result code, you should be returning a JSON payload that contains a minimum of two pieces of data – a unique error code for the issue, and a message aimed for the consumer/developer of the application to help them debug.  For example, if the consumer tried to create a new account without including all of the mandatory fields, this would be a useful error to return:

{ "error" : 16, "debug" : "The mandatory field for balance was missing in the request" }

Some recommend returning a user message also, which can be useful.  Others use the error code to create their own message to pass to the user.

10.  Finally, what else should we be thinking about for using the API in production?

There are many considerations for using APIs in production – here are just a few:

How are you going to make money from your API?  Are you thinking about a transaction cost per call, freemium, capped model, or something else?  Many of these systems are going to require some kind of API metering – which isn’t necessarily hard, but is definitely something else to consider.

Are you going to rate limit your API?  How are you going to prevent a rogue customer, application, or process, who wishes to call your API hundreds of thousands of times?  Fortunately, there are answers to this – including RFC6585 which specifically deals with rate limiting – but again, something that you should be considering.

Should your API provide cached results? Is this something that can improve the performance for your consumers, and also prevent unnecessary calls to back end databases and other systems?

How is your API going to work over a low bandwidth connection?  Your API might work great on your FIOS line here in the US, but do consumers get the same experience when calling the API from a J2ME application from a cell phone in the middle of Africa?  There are many ways to simulate throttled connections and this should be something that is definitely worth testing for.

Finally, and arguably most importantly, how can you get everything to go through your API?  Instead of thinking of an API as a companion to your existing Web-based applications, what would it take to push everything through this API – treating the API as a single source of truth?  It might sound scary, and undoubtedly it’s additional work to have everything using the API – but a single API that every application uses has the potential to offer a lot of re-use and sharing as you develop your API over time.

Transferring Data via Bluetooth on Android (android-btxfr)

Recently, I’ve been working on some code to transfer images and other data between Android devices using Bluetooth.  While I could have used the Basic Imaging Profile (BIP) of the Bluetooth 4.0 specification, this particular application has specific requirements that would have been difficult to implement using BIP.  To overcome this, I ended up building an application that instead relies on the Serial Port Profile (SPP), exchanging data using the RFCOMM protocol.  

The SPP implementation on Android is nice, but only offers the fundamentals of an InputStream and OutputStream.  While this provides the basics of sending and receiving bytes, it doesn’t handle data integrity, progress updates, threading, or any of the other requirements often needed when sending data between two devices.

The result from my recent work is an Android library called android-btxfr, which I’m happy to share through my Github repository.  android-btxfr is lightweight library designed to send and receive any type of data between Android (API 15 and higher).  It can be used to exchange text, files, photos, videos, sounds, and literally any other type of binary data.  The library supports anything that can be put into a byte stream and includes digest checking to ensure data integrity.

The library exposes two thread types (ClientThread and ServerThread) depending on whether you are sending or receiving data.

Receiving data is easy. Simply run the server thread, passing the paired bluetooth device and handler. The handler will be then called with the following messages:

DATA_PROGRESS_UPDATE – Data is being received by the other device. The message contains the progress of the data being received.
DATA_RECEIVED – Data has been fully received from the other device. The message will contain the actual payload (a byte stream of the image, video, etc.)

There are other message types to handle failure conditions.

The client thread works in a similar fashion. To send data, invoke the client thread, passing the paired bluetooth device and handler. The handler will be called with the following messages:

READY_FOR_DATA – Indicates that the connection has been established, and data can be sent.
SENDING_DATA - Indicates that data is being sent to the other device.
DATA_SENT_OK – Indicates that the recipient received the payload.

Again, there are other message types to handle failures.

To show all of this in action, I’ve put together a sample application, which can be found here.  This app uses the android-btxfr library to send captured photos between devices. 


Enabling x86 Android Emulation

If you’ve undertaken any Android development, you’ll have likely found that the Android emulator can be painfully slow – to the point where the majority of developers I know use a physical device to do any development at all.  The primary reason behind this is that the default emulator is emulating an ARM based chipset on x86 hardware, and the translation between these two architectures is of course costly.  What many of these developers may not realize (and I didn’t until very recently) is that Intel have released a x86 Android emulator.  The x86 emulator has a few caveats (and of course cannot run any ARM-only libraries, such as the Google Play APIs), but overall can be used to speed up the performance of testing apps in the emulator by leaps and bounds.
This is how to get it working:
1.  In the Android SDK Manager, ensure you have API Level 15 or higher installed.  Under the API of your choice, install the Intel x86 Atom System Image:
2.  Under the Extras folder, install the Intel x86 Emulator Accelerator (HAXM) module:
3.  After you add the HAXM support through the SDK manager, you still need to install the HAXM package.  To do this, navigate to the Extras/Intel/Hardware_Accelerated_Execution_Manager folder under your installed Android SDK path.  Run the .dmg in this folder to install the support.  As part of the installation, you’ll be asked how much RAM to allocate/partition.  On my 16Gb MBP, I have chosen a 2Gb allocation.
4.  This is really important (for Mac OS X Mountain Lion users).  Go to this knowledge library page on Intel’s HAXM site and install the 1.0.4 hotfix.  If you do not install this hotfix, you will likely get a kernel panic when you try to start the AVD.
5.  Create a new AVD, or edit an existing AVD.  Ensure that the CPU/ABI is set to Intel Atom (x86).
You can also increase the RAM up to the limit that you set during the HAXM installation.  Also, you should ensure that the “Use Host GPU” check box is enabled as this will allow the emulator to use OpenGL ES on the host for increased performance.
With that you should be set!  If you are editing an existing AVD, I recommend checking the “Wipe user data” checkbox before starting the image.  (Otherwise you might find that the emulator will hang during start up).  
If everything is working OK, you should receive a message that HAXM has been enabled, and your AVD should boot in several seconds (as opposed to several minutes) and be lightning quick to use!

An Objective View of MEAPs

I recently had the opportunity to put together some research for a customer who has been interested in the MEAP (Mobile Enterprise Application Platform) space. My premise is that the market has become flooded with MEAPs (Mobile Enterprise Application Platforms, as coined by Gartner), yet most of them are fundamentally taking organizations and developers down the wrong path when it comes to developing mobile applications. The problem is that MEAPs demo really well in front of the CIO… “Wow! You just hit F5, and your application is compiled and deployed to iOS, Android, Blackberry devices… Where do I sign?” – yet the reality is very different. Namely:

Language Abstraction – Many MEAPs have their own language that claim to be similar to Java or a flavor of JavaScript. Even if it is the same language, there is always something new to learn. Also, developers tend to shy away from learning any language that’s vendor specific (APEX on anyone? ;–)

Language Limitations – When you create a language that abstracts other languages you always end up serving only the lowest common denominator. Often there are ways of coding styles and nuances supported in the native language that the MEAP won’t expose because it’s not on other platforms.

Platform Limitations – Time has shown that platform abstraction doesn’t work (do a search on Wikipedia for cross platform RAD tools if you don’t believe me). Also, platforms change quickly. What happens if/when the next version of iOS is released? You have to wait for your MEAP vendor to catchup before you can use any of the features.

UI Limitations – Following on from the previous point, many of the controls that MEAPs offer also follow the lowest common denominator rule. For example, Cocoa Touch has a neat feature called a “Half Page Curl Transition”. If you abstract your UI to a MEAP vendor, how is this supported on other platforms? Either a) it’s not (so by default you can’t use it on iOS), b) you can only use it on iOS (which breaks the promise of a MEAP) or c) it’s implemented as a hack job on all platforms.

Tooling – MEAP tooling is often Web based, or bundled as an Eclipse add-on – but in both cases it often doesn’t fit in with the other tools that developers use today (e.g. ALM, refactoring, unit testing, etc.). Also, many of the MEAP vendors seem to be aiming their toolsets towards business analysts. When are we going to let this one go? Business analysts have an important role to play in teams, but they shouldn’t be developing UI, and they shouldn’t be writing code.

Debugging – Let’s say you create your application with a MEAP, and then it crashes 1 time in every 10 (i.e. one of those really nasty bugs to find). What are you going to do? a) Reach out to Apple? I suspect they won’t help you. b) Search the web for other people with the same issue? Could be difficult to find. c) Pay the MEAP vendor even more money to investigate your issue? Ah, that’s the one…

Data Abstraction – Many MEAPs offer connectors to databases, XML files, SAP, etc. Not only are these costly, but many are just pass-through connectors, so as a developer you don’t get any control over the connection. Want to implement synchronization? Want to change the formatting or query for better optimization? Probably not going to be possible.

Difficult to Extend – Many MEAPs don’t extend very easily. Found a new JavaScript library that you want to use in your application? How about a native control that you’d like to display? Could be tough. Some MEAPs do offer bridging to native code – but in which case, why not just write the whole thing in native code to start with?

Vendor Lock In – The sum of all the above leads to quite the definition of vendor lock in. Chances are by the time you deploy your first application you’ll be signed up with an expensive support and service agreement, with your developers working on code in a language that they’ll never be able to re-use, on a platform that won’t go anywhere.

I’ve extended this into a presentation that you can find below – which cover the above points in more detail, plus outline some general alternative approaches to creating applications without the dependency on a MEAP framework.

Based on other people’s experience with MEAPs, am I missing anything?

Tips, Tricks, and Recommendations for HTML5/Mobile Web Development

Over the past few months I’ve been fortunate to have worked with several customers creating Mobile Web applications for different devices. These have included an iPad based Mobile Web app for a healthcare provider, a cross-platform Mobile Web app for a commercial real estate broker, and an Android tablet solution to allow scientists to research experiment details from the comfort of their lab.

From these projects, I’ve come up with a list of tips, tricks, and recommendations that I wanted to share if you are looking to develop your own Mobile Web applications. Hope you find them useful…

Understand the differences between Mobile Web and hybrid applications

It’s important to make an early decision on whether your application is going to be pure Mobile Web (the user accesses it through the browser on the device) or hybrid (the user launches an application with an embedded control to display web based content). The decision to use the mobile browser or to have a dedicated hybrid application will likely be determined by the functionality the application requires. For example, obtaining the GPS location from the device can be performed perfectly well inside the browser, but accessing the camera from a Web page needs a hybrid application to provide the functionality.

In my experience there are three common features that drive developers towards a hybrid application: 1. Access to the camera. 2. Access to local contacts on the device. 3. Deployment to the AppStore/Marketplace. The first two are to overcome limitations of what can and can’t be accessed through the mobile browser (and is something that Mozilla is trying to tackle through WebAPI). The latter one is probably the most important to understand however – as while a hybrid solution will enable the application to be published to the app stores, extreme care needs to be taken to ensure that the application will not be rejected. This is most common with applications destined for Apple’s AppStore (if Apple view your application as a single container for web content with no apparent native functionality, they will more than likely reject it).

If you do take the hybrid approach, you really have two options to build the application – you can either set out and build a native application, embed a WebView control and then hook different events to create your own bridge between the two. This can be very useful if you only have a small piece of Web functionality that you need to embed in your application. Alternatively, you can consider using a framework such as PhoneGap (now known as Apache Cordova). Using Cordova is not without it’s challenges (for example, with cross domain scripting and client side certificate authentication), but it can definitely give you a head start especially if the majority of your application is going to be based on mobile web content.

Setup a robust development and testing environment

Setting up a robust development environment might be viewed as obvious for most of us, but tools for developing Mobile Web applications are still relatively immature, so it’s an important area to get right before you start your first app. In the most basic setup, you are going to need three things to be successful:

The first is a great IDE for HTML development. You’ve probably got your favorite already, but a strong IDE with as much JavaScript code completion support as possible will be your friend. Personally, I switch between TextMate, Visual Studio 2010, and WebStorm depending on which platform I’m working with. It’s also interested to see where Adobe are headed with their toolset.

Secondly, you are going to need a browser capable of inspecting the DOM and doing JavaScript debugging. Personally, I use Safari for doing this, but Chrome and/or IE9 will equally provide you the tools that you need. The important thing here is not so much the choice of the browser, but the understanding of how to breakpoint JavaScript code and inspect elements both on and off the page.

Finally, you’ll need some kind of device, or device emulator. Switching the user agent on a desktop browser will only get you so far, and eventually you are going to need to test on something representative of the device that the user will be using. If you are developing an application that will be primarily used on iOS devices, I would certainly recommend a Mac (as the iOS simulator is very robust). If a Mac doesn’t float your boat as your development machine however you could consider a hosted solution such as MacinCloud or simply do all your debugging using an iPod touch. There are a few PC based utilities that claim to emulate mobile safari/iOS, but I’ve had a poor experience with all of them.

For Android, I tend to avoid the emulator whenever possible (it’s a resource hog) and instead have a selection of devices that I can use for debugging on the fly. I’ve found that the key for Android testing is to have a selection of devices with preferably different resolutions and running different versions of the OS (e.g. a separate device running 2.1, 2.2, 2.3, and 4.0 should cover most of the current market, unless you have a need to go back to 1.6 for some reason). If you don’t have access to physical handsets, you may want to consider one of the testing providers such as Perfecto Mobile. They have a variety of devices that you can rent, covering many different platforms.

Use client side JavaScript instead of server side scripting

If you’ve been developing Web applications for some time, especially enterprise facing applications, you’ll be used to having a lot of the presentation and application logic tied up in server side scripts, maybe running server-side ASP, ASP.NET, JSP, PHP, etc. When developing Mobile Web applications however, things need to change. While server-side scripting will of course still work for a mobile application (and might be very tempting as you start to write your first application), it quickly creates a tight coupling between your device and the server. In the old days where you were accessing the server from a desktop browser on the same network, this wasn’t a problem – but once you move the experience to a mobile device with a potentially patchy network connection, the last thing you want to be doing is relying on the server side for generation of pages and views. If your mobile web application needs to do a roundtrip to the server when you hit the “Next Page” button, you’re going to be heading for a world of hurt.

The answer is to move as much (if not all) of the application logic to client-side JavaScript. This might be a painful exercise as you translate the move from an MVC server side framework to handcrafting page navigation using client side JavaScript, but the pay off will be worth it. If you have all of the application logic locally, together with pre-fetching as many of the pages into the DOM when your application first loads, you effectively disconnect yourself from the server side which makes performance much better and also moving to offline much easier. Of course, you still want to communicate with the server side – who doesn’t? – but this should be done via a set of asynchronous REST/JSON calls to bring data into the application rather than relying on the server to generate HTML for your application.

Design for running offline

Related to the previous point, you should also start thinking about how your application could run offline, even if you have no plans to do so. This will put you on a good architectural path, and will also mean that your application will work if and when network connectivity is lost. There are plenty of articles explaining how to enable offline access in HTML5 applications, so I won’t plan to cover here – other than to say you’ll be creating a cache manifest for your application, specifying the files to go into your cache, enabling the scripts for checking the cache when your application starts, and handling control logic accordingly (e.g. when you hit that submit button, you’ll want to know whether there is network connectivity before making the call to the server!).

If there’s one piece of advice that I can offer here however (and we learned this the hard way) it is to design for offline first, but implement last. Do all of the right things to support offline in your application, but don’t enable it until you are close to the end of your development cycle. If you enable it too early, it can cause mayhem with the development team – as your developers could end up debugging against a version of the application that could be slightly older – or the cache doesn’t get refreshed in the way it should. This doesn’t application to local storage – this is fine to access during development – I would just recommend not enabling the cache manifest until you go into UAT.

Select the right UI framework for your needs

Almost every other day there seems to be a new HTML UI framework released, and mobile frameworks are no exception. At Neudesic we’ve had most experience and success using jQuery Mobile, but have equally done work using Sencha, Dojo and others. As all the frameworks offer slightly different combinations of controls, I’ve found one of the tricks for selecting a suitable framework is to first build out a list of the controls that you are likely to need. For example, in one project we developed a set of paper prototypes (side note – I really dig UI Stencils for this) and realized that we would be creating a multi-tabbed application, with many lists on each page. Knowing what controls we were likely to use ahead of time made selecting the framework easier, and also put into perspective what controls we would have to build from scratch.

The good news is that most of the frameworks have demo pages/sites available, so that you can check them out beforehand without having to download anything. This can be a great way of testing the controls across a different number of devices, as well as getting a feel for the performance. My rough order of magnitude is that HTML based mobile UI will feel around 85% of a native control – it will look similar, react similar, but you just know that there’s this 10 – 15% gap that doesn’t quite feel native.

Understand the caveats with implementing maps in Mobile Web applications

Related to the last point, many applications have a need to display maps and pinpoints, and this will likely remain true for many mobile web applications that you might be creating. Based on experience, there are a couple of caveats that need to be understood before you head down this path.

Firstly, performance on Mobile Web map controls is not to par with native controls. Using Google Maps in Safari on iOS seems sluggish when comparing it to using MapKit in a native iOS application. I’m not sure what optimizations have been done in MapKit to give it the performance it has, but the difference is quite noticeable. As a result, if your application has a fundamental need to do a lot of mapping (i.e. if this is it’s primary function) you may want to consider a hybrid approach where you navigate to native pages for the mapping as part of your application.

Secondly, the web control for Google Maps (and this probably applies to other mapping controls) likes to “own” the page – which can put it into conflict with UI frameworks such as jQuery Mobile. For example, when you change pages in jQuery Mobile, the DIV element of your current page is set to hidden, and the DIV element of the new page to block. If your map control is embedded on a page that gets set to hidden this can cause Google maps to have a hard time. We’ve experienced random behavior such as the map control not updating or repainting correctly when it is brought back into focus. This can be overcome by an event on the page load to refresh the map canvas (example below), but it’s one of those bugs that takes a lot longer to find than it does to fix.

$(‘#mappage’).live(‘pageshow’, function() { google.maps.event.trigger(map, ‘resize’); });

Think ahead for non-standard UI elements you are likely to need

While frameworks such as jQuery Mobile will provide standard controls such as buttons, lists, labels, and radio boxes, your application will likely have a need for elements and controls that are non-standard. These can include tables, grids, and image carousels to name a few. Many of these can be created using custom controls, but before going down that path, I always try and ask myself two questions:

Firstly, if the control does not exist, does that mean a better UI nuance is available for the device? For example, there are few mobile web controls for displaying datagrids on mobile devices. Rather than force-fitting a solution that might not work well on a 3.2″ screen, think about what alternative solutions could be used instead. For example, maybe a series of cascading list controls would actually provide for a better user experience over some custom hacked-together table control. When in doubt, try to look at how other mobile applications have used controls to represent a similar data set.

Secondly, if the control does seem to fit, but it’s just not included in the standard UI framework that you’ve chosen, think about searching for a third party solution before re-creating something new. This can apply to image carousels (PhotoSwipe is one of my favorite controls for doing this) as well as charting (there are several really good JS based charting controls out there).

Make your mobile web app look and feel like it belongs with native applications.

Why not go that extra step and have your mobile application look like it belongs with other native applications on the device? A couple of small recommendations for this one:

Firstly, never show the address bar in your mobile application. Simply use a <viewport…/> tag to have your application run in full screen mode. The user will still be able to get to the address bar, but it will be hidden from view by default. (side note – jQuery Mobile now performs this automatically without the need to do “scroll to” events in JavaScript).

Secondly, if you are targeting iOS devices, consider using Cubiq’s AddToHome JS library. This is an excellent add on that will display instructions for the user to add the application to the iOS home screen, enabling the application to have it’s own icon and run completely full screen when launched.

Don’t go creating your own username and password database

Have users sign on to your application can be very useful for security of the application and for storing preferences and other settings. Unless you have a very strong reason however, I recommend that you avoid creating your own username and password database for your application. Doing so can seem really easy at first, but as your application gets more popular you’ll be left with a nightmare situation of having to deal with registration issues, password resets, and all of the other administration that comes with owning your own identity provider.

If you are building a mobile web application for the enterprise, I suspect you’ll already be thinking about this – either hooking in to an existing Active Directory instance or other identity provider (although you’ll likely need to consider how this will work outside the firewall when your mobile users are accessing your application via a public connection).

If you are building a public-facing application however, an efficient solution can be to federate with an existing identity provider. Chances are your users already have a Google, Yahoo, or Facebook account. Why not take advantage of this and use this sign-in information to authenticate the user for your application? This can be done in a couple of different ways – either with a native SDK from one of the providers – or using a federated service such as Microsoft Azure’s Access Control Service. This is a simple service to setup, which will enable you to configure a list of providers and returns a bag of claims to your application which you can use to match up with a list of settings, preferences, etc. There are a few caveats with this approach, especially as some of the providers return the information via a post back (which can really upset your mobile application if you’ve pre-fetched all of the pages in to the DOM beforehand). This is something that I’ve written previously about in this post.

Make your Mobile Web application perform well

It might sound obvious, but if you want your Mobile Web application to come anywhere near to the performance of a native application, you’ll want to keep a keen eye on performance. Generally, I’ve found there are three main causes of bad performance in Mobile Web applications:

First is server-side generation of the UI and round tripping (as discussed in the point on client-side JavaScript earlier). If you are generating any of the UI on the server-side or making any synchronous server-side calls, you are more than likely to run in to trouble.

Second is too many CSS effects/transitions. Many of the UI frameworks, including jQuery Mobile, include several page transitions for when the user navigates between different pages. Unless you are exclusively targeting iOS devices, I would recommend turning all of these off. Many of the older Android devices don’t implement a version of Webkit that supports hardware acceleration – plus they are running on less capable hardware – so to avoid creating an application that stutters on Android devices, it’s best to disable any transitions and effects.

Finally, watch out for too many registered JavaScript events (especially on the class level). The JavaScript performance on mobile browsers can be much lower than desktop equivalents, and if you are not careful you can end up where the performance of the browser is being compromised by too many registered events. Often this will only add 100ms to various events, but combine this with specific events (such as a button tap) that must immediately navigate to another page, any delay over 100ms might be enough that your user thinks that the button wasn’t pressed correctly. They’ll press it again, and before you know it you have two JavaScript navigation events that you’ll need to handle.

Wrapping up

A bit of a lengthy post, but I hope that this is useful if you are heading down the path of developing Mobile Web applications. If you’d like more information on this, or maybe to share with colleagues, I’ve uploaded this presentation to SlideShare that goes through the above list in some detail.

Authenticating with Google, Facebook, and others from your jQueryMobile Application

In my last post, I showed how to implement authentication using Google, Facebook, etc. for your iOS application – using the Windows Azure Toolkit for iOS.  This works well for iPhone applications written in Objective C, but what if you are developing a Web based mobile applications that span multiple platforms?  Given that everything is using Web pages, you would hope that it would be a little easier, but things can get tricky – especially if you are using jQueryMobile. 

Having implemented this a couple of times now, here is a rough guide of how to integrate AppFabric ACS (Access Control Service) authentication into a jQueryMobile application. (There is already a ton of documentation of both jQueryMobile and ACS, so I’m assuming that you understand the basics of how these both work).   

Step 1:  Create your own provider selection screen

When you first start playing around with using ACS on mobile web browsers, the first thing you’ll notice is that the default login page isn’t that nice. 


While the functionality of logging in will work, users have to pinch zoom to be able to read the buttons, which isn’t a great experience.  It also doesn’t fit in with any jQueryMobile theme that you may have created.  To overcome this, we can create our own provider screen. 


To build something similar to the above, I’ve used a jQueryMobile Dialog (which has an automatic border as well as a background effect).  The basic code for the screen looks like the following:

<!DOCTYPE html>
    <title>Select Login Provider</title>
    <div data-role="dialog">
        <div data-role="header">
            <h1>Select Login Provider</h1>
        <div data-role="content">
                if (ViewBag.JSONProviders != null)
                    var providers = Json.Decode(ViewBag.JSONProviders);
                    foreach (var provider in providers)
                        <button type="button" onclick="javascript:window.location.href='@provider.LoginUrl'">@provider.Name</button>

As you can see from the above, the form is built by parsing a JSON object containing a list of identity providers and creating buttons for each provider – setting a name for a button and setting an on click action to the URL.  (The above code uses the Razor-based syntax for  ASP.NET MVC, but the same will work just by using JSON calls in regular Javascript). 

Two things to note here:

1.  It’s really important to use window.location.href instead of an <a> anchor when linking to the provider – otherwise you’ll break the AJAX model of your jQueryMobile app and a new browser window will be launched (which looks horrible, especially in full screen web applications).

2.  You are probably asking yourself where the JSON objects actually come from.  This brings us to our next point…

Step 2:  Make a call to the ACS JSON endpoint

The buttons in the form are based on identity providers, which you likely setup when you configured ACS.  These providers can be extracted as JSON objects using a JSON based endpoint that the ACS service providers. 

Here’s the URL of the JSON endpoint for ACS v2.


{0} is the namespace of your ACS service

{1} is the realm within your ACS service

{2} is an optional URL (which must be HTML encoded) that specifies where to return the browser once authentication has been completed.  Remember, if you are using AJAX navigation, then you’ll want to pass in the correct #-prefixed syntax.  For example a return URL of the following:


Will instruct the ACS service to return to the Accounts page in your jQueryMobile app.

Again, you can make the call to the JSON endpoint using Javascript, or if you are using ASP.NET MVC like in Step 1 I would recommend creating a controller action called Providers which passes the return JSON object in a ViewBag. 

Step 3:  Launch the providers screen from your app

Finally, once you have your provider screen created, you’ll need to call it when authentication is required.  There are a couple of different ways of doing this – if you are using Javascript only, then create and maintain a variable called claims – which corresponds to the claims bag returned from the service (when the ACS service returns it does a post back to your application so that you can capture the claims).  Secondly, if you are using ASP.NET MVC then you can create a second action on the Account controller called claims with something similar to the following:

public JsonResult Claims()
    return Json(string.Join("n", ((IClaimsIdentity)this.User.Identity).Claims.Select(c => c.ClaimType + ": " + c.Value).ToArray()));

This will return the claims bag directly from the User.Identity property from the controller.

Well, just a short overview, but if you are thinking of implementing Google and Facebook authentication in your jQueryMobile application, hopefully this has been of some help.