-
Notifications
You must be signed in to change notification settings - Fork 132
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.
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 generated by the Puget Sound onebusaway-webapp will never collide with a UUID 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. 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 create 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 startup, an API key with the specified name will be created 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>
For the existing OBA mobile apps to work with OneBusAway, you must add the following keys to the data-sources.xml file for the opentripplanner-api-webapp:
-
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 URL would be: http://your.oba.server/onebusaway-api-webapp/api/where/agencies-with-coverage.xml?key=v1_C5%2Baiesgg8DxpmG1yS2F%2Fpj2zHk=c3BoZW5yeUBnbWFpbC5jb20=
The existing iPhone and Android apps both have settings where you can update the OBA server 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.
To be clear, the above keys should NOT be used in your own mobile app, these keys are reserved for the exiting OBA native open-source mobile apps.
We're currently working on a way to make the existing mobile apps "regionalized" to support multiple OBA server instances.
Having problems? Check out our Troubleshooting page to see if we have a known solution.