Skip to content

API Webapp Configuration Guide

Jump to bottom Edit New page
paulcwatts edited this page Jan 20, 2013 · 38 revisions

This guide will instruct you on how to configure an instance of onebusaway-api-webapp. These are specific configuration instructions, part of your larger OneBusAway installation. The onebusaway-api-wepapp powers the OneBusAway REST API.

Managing API Keys for a Single OBA Server

The API service typically expects an API key with each request, as identified by the key parameter. The API key is a loose form of authentication that can be used for simple access control and logging purposes. It also supports basic connection throttling to prevent a single client from abusing the API service.

Automated software-based generation of API keys is implemented in the onebusaway-webapp using the [Java UUID.randomUUID()](http://docs.oracle.com/javase/6/docs/api/java/util/UUID.html#randomUUID() function. Per the Java documentation and RFC 4122: A Universally Unique IDentifier (UUID) URN Namespace, generated UUIDs will be uniquely identifiable across multiple OBA instances for the foreseeable future (i.e., until around 3400 A.D.). In other words, a UUID key generated by the Puget Sound onebusaway-webapp will never collide with a UUID key generated by the Tampa onebusaway-webapp. This is possible through the use of uniquely identifying information for the server OBA is running on as well as unique timestamps on each server. Please see RFC 4122 for more information on UUIDs.

Managing API Keys using the Admin Interface

You can manage (add, edit, and delete) API keys using the OneBusAway admin interface if its included in your OneBusAway deployment.

It is strongly recommended that you generate new API keys using the "Generate random key" link on the Admin Interface, so that new keys are guaranteed to be unique across multiple OBA servers.

Browse to the following url:

http://localhost:8080/admin/api-keys.action

where the base URL is changed to reflect your installation location. Through this interface, you can add, edit, and delete API keys, along with determining how much traffic is allowed from the specified key.

Add an API Key in data-sources.xml

Its possible to add an API key directly in your data-sources.xml configuration file. Simply add a section like:

<bean class="org.onebusaway.users.impl.CreateApiKeyAction">
  <property name="key" value="YOUR_KEY_HERE" />
</bean>

On application start up, an API key with the specified name will be added if it does not already exist.

If you need to add multiple API keys, add one bean for each new key, such as:

<bean class="org.onebusaway.users.impl.CreateApiKeyAction">
  <property name="key" value="YOUR_KEY_HERE_1" />
</bean>

<bean class="org.onebusaway.users.impl.CreateApiKeyAction">
  <property name="key" value="YOUR_KEY_HERE_2" />
</bean>

Please note that the recommended practice for generating new API keys is to use the "Generate a random key" link on the OBA Admin interface in the onebusaway-webapp, as discussed in the first section, so that keys are unique across multiple OBA servers.

Multi-Region Mobile Apps - API Key Management Across Multiple OBA Servers

For an app to work across more than one OBA server instance (e.g., Puget Sound and Tampa), each OBA server will need to have knowledge of the app's API key to permit access to the API. The question then becomes: "How are keys for multi-region apps generated and shared with OBA servers?"

This question applies to three groups of apps that interface with an OBA REST API:

  1. The official OBA Android, iPhone, and Windows Phone mobile apps
  2. Existing 3rd party mobile apps (e.g., in Puget Sound)
  3. New 3rd party mobile apps that haven't yet been created

Using the official OBA Mobile Apps with your OBA Server

For the official OBA mobile apps to work with your OneBusAway server, you must add the following keys to the data-sources.xml file for the opentripplanner-api-webapp (or add them via the onebusaway-webapp "Add Key" management console):

  • Android: v1_BktoDJ2gJlu6nLM6LsT9H8IUbWc=cGF1bGN3YXR0c0BnbWFpbC5jb20=
  • iPhone: org.onebusaway.iphone
  • Windows Phone 7: v1_C5+aiesgg8DxpmG1yS2F/pj2zHk=c3BoZW5yeUBnbWFpbC5jb20=

NOTE: If you're testing the Windows Phone 7 key with your OBA API from a browser, note that the key contains two reserved characters ("+" and "/") that need to be encoded to form a valid URL. Here's the encoded key - v1_C5%2Baiesgg8DxpmG1yS2F%2Fpj2zHk=c3BoZW5yeUBnbWFpbC5jb20= - so a sample test request URL would be: http://your.oba.server/onebusaway-api-webapp/api/where/agencies-with-coverage.xml?key=v1_C5%2Baiesgg8DxpmG1yS2F%2Fpj2zHk=c3BoZW5yeUBnbWFpbC5jb20=

To be clear- the above keys should NOT be used in your own mobile app, these keys are reserved for the existing OBA native open-source mobile apps.

The official OBA iPhone and Android apps both have options in the "Settings" menus where you can update the OBA server API that the app is pointing at. So, for testing you can download the existing apps from the iPhone App Store or Google Play store and change the URL to point to your server.

We're currently working on a way to make the official OBA mobile apps "regionalized" to support multiple OBA server instances through the use of a centralized OBA server directory, so users of the apps can seamlessly use the apps in multiple cities. We will update this wiki with the process of adding your OBA server instance to that directory so your city appears as an available region once the exact methodology and interface is determined.

Existing or new 3rd party mobile apps - API Key Generation and Sharing Process

This section discusses the process agreed upon by the OBA community for generating and sharing API keys that will be used with more than one OBA REST API server (e.g., OBA servers in different cities).

The following rules apply:

  1. Each each app MUST use a SINGLE API key across multiple OBA servers - For example, if an app uses the key hf9823h02h02.... to access the OBA REST API in Puget Sound, it will use the same key hf9823h02h02.... to access the OBA REST API in Tampa.
  2. A key that is used across multiple OBA servers MUST be a UUID (e.g., it MUST be automatically generated using the "Generate a random key" function on the OBA Admin panel) - UUIDs are guaranteed to be unique across multiple OBA servers, which will avoid key collisions (i.e., different apps using the same API key).

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

  1. The app developer must request an API key from the geographically-closest OBA server admin - The OBA server admin will ensure that the app developer agrees to the OBA "Terms of Service (TOS)", and then will provide an UUID API key (e.g., a key generated using the "Generate a random key" function on the OBA Admin panel in the onebusaway-webapp).
  2. The app developer will contact each regional OBA admin that they want to interface with - Each regional OBA server admin will again ensure that the the app developer agrees to the TOS for that particular OBA server instance. The app developer will then provide each regional OBA admin with the original UUID key that was assigned to their app by the original geographically-closest OBA server admin, and each regional OBA server admin will add that UUID key to their OBA server instance.

Troubleshooting

Having problems? Check out our Troubleshooting page to see if we have a known solution.

Add a custom footer
Add a custom sidebar
Clone this wiki locally