Proposal - Multi-Region API Key Management for Multiple OBA Servers

[Sean Barbeau]

Hi all,
One huge strength of OneBusAway is the mobile apps (Android, iPhone, and Windows Phone).

There are currently plans to expand these apps using a multi-region design so they can be used outside of Puget Sound.

As OneBusAway continues to mature and expand, we'd like the ability to make new 3rd party OneBusAway apps created in one city (e.g., Tampa) to work in another (e.g., Atlanta).

The key issue here (pun intended) is API keys - how are they generated and managed to seemlessly allow access across multiple OBA servers, with low overhead for both 3rd party app developers and OBA admins?

A few of us have discussed this, and come up with a proposal here (see 2nd section - "Multi-Region Mobile Apps - API Key Management Across Multiple OBA Servers"):
https://github.com/OneBusAway/onebusaway-application-modules/wiki/API-Webapp-Configuration-Guide

Background:

Currently, pseudo-random API keys can be generated using the onebusaway-webapp admin website.  These auto-generated keys are Universally Unique IDentifiers (UUIDs), which are guaranteed to be unique across multiple servers for the foreseeable future (see proposal page for details).  This solves the hard problem of figuring out how to avoid key collisions, and does it in a decentralized manner that avoids us having to keep a centralized keystore.  Very nice.

So, we will leverage these UUIDs for the guidelines surrounding multi-region API key management.

Here are the guidelines for 3rd party mobile app developers and OBA server admins when generating and using keys:

1. Each each app should use a SINGLE API key across multiple OBA servers - This reduces the burden on app developers so they don't need to manage multiple API keys in the app.
   
2. A key that is used across multiple OBA servers MUST be a UUID - This avoids key collisions.
   

Here's the process we will use for a 3rd party app to become "multi-region":

1. The app developer should request an UUID API key from the geographically-closest OBA server admin (or, if they're already working with a OBA server, the server admin they are currently working with).  The OBA server admin will ensure that the app developer agrees to the local OBA Terms of Service (TOS), and then will provide a UUID API key.
   
2. The app developer will contact each regional OBA admin that they want to interface with, and provide the UUID generated by the OBA server from #1 above.  The regional OBA admin will do any desired vetting of the app (regional TOS, etc.), and the admin may add the provided UUID key to the regional OBA server, at their discretion, to make the 3rd party app available to their customers.

Existing OBA mobile apps (Android, iPhone, Windows Phone, Windows 8 (?) ) are grandfathered in with their existing API keys.

Open question:

Should we programmatically append a human-readable prefix (e.g., issuing server name) to the API key, to make it easier to track the source of API keys across multiple servers?

For example, a normal UUID would be:
hf9823h02h02....

A UUID key with an added human-readable prefix, which makes it easy to see it came from USF, would look like:
onebusaway.forest.usf.edu-hf9823h02h02....

If we decide this prefix is useful, I'll amend the above wiki page and open a Github issue for this.  If not, we can just stick with plain UUIDs.

Any feedback on the entire proposal is appreciated.

Thanks,
Sean