-
Notifications
You must be signed in to change notification settings - Fork 133
API Webapp Configuration Guide
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.
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.
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.
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.
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:
- The official OBA Android, iPhone, and Windows Phone mobile apps
- Existing 3rd party mobile apps (e.g., in Puget Sound)
- New 3rd party mobile apps that haven't yet been created
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.
NOTE: There is currently an issue that affects configuring the OBA iPhone app to point at your OBA server. The current workaround - DON'T hide the keyboard after entering the API endpoint for your server in the Settings screen. Instead, after you've typed in the address for your server, just tap the "More" button in the upper-left corner to go back to the previous screen. If you hide the keyboard, the app may crash and may not properly save your server API address.
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.
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:
-
Each each app should 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 keyhf9823h02h02....to access the OBA REST API in Tampa. - 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":
- The app developer should request an API key from the geographically-closest OBA server admin, or the server admin they are currently working with - 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).
- The app developer will contact each regional OBA admin that they want to interface with - Each regional OBA server admin will ensure that the the app developer agrees to the TOS for that particular OBA server instance, and any other regional guidelines. 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. Whether or not to add a new 3rd party app is left to the discretion of regional OBA admins.
Having problems? Check out our Troubleshooting page to see if we have a known solution.