-
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 as well as the OneBusAway GTFS-realtime Export API.
The REST 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() 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 (example in my case: http://localhost:8080/onebusaway-webapp/admin/api-keys.action). Through this interface, you can add, edit, and delete API keys, along with determining how much traffic is allowed from the specified key.
Note that there is currently an issue with API key management from the Admin Interface.
IMPORTANT - Please note that by default randomly-generated API keys will have a 100ms rate limit (i.e., "Min Api Request Interval" in the web admin console) - in other words, more than one request from a client can't occurred less than 100ms apart, otherwise the subsequent requests will get a 401 permission denied error response. If you trust the application using the key, you can change this to 0ms to remove the rate limit and allow more frequent requests. For production apps that will be used by a large number of users, the rate limit will need to be set close to 0ms to avoid returning error messages to users. When you add the API key by putting it in data-sources.xml (see below), no rate limit is applied to that key.
It's 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.
When you add the API key by putting it in data-sources.xml, no rate limit is applied to that key (see previous section for more details on rate limits).
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:
v1_C5+aiesgg8DxpmG1yS2F/pj2zHk=c3BoZW5yeUBnbWFpbC5jb20== -
Windows 8:
693c0a55-9ef0-4302-8bc3-f9b2db93e124 -
Fire Phone:
v1_BktoDJ2gJlu6nLM6LsT9H8IUbWc=cGF1bGN3YXR0c0BnbWFpbC5jb20=(same as Android) -
Alexa (for Amazon Echo, etc.):
e5c0e97a-729d-4fdb-a3ca-2fccb20ac3ab -
Pebble Smartwatch:
48d59e79-ed33-4be0-9db3-912f8f521fec
NOTE: If you're testing the Windows Phone app 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%3Dc3BoZW5yeUBnbWFpbC5jb20%3D= - so a sample test request URL would be: http://api.tampa.onebusaway.org/api/api/where/agencies-with-coverage.json?key=v1_C5%2Baiesgg8DxpmG1yS2F%2Fpj2zHk%3Dc3BoZW5yeUBnbWFpbC5jb20%3D=
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.
After you've tested your server with the apps, you can send a request to the OneBusAway Developer group to ask to be added to the OneBusAway Multi-region Initiative to make the official OBA mobile apps available in your city.
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 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.
See the Regions API response otpContactEmail field for contact info for each region.
Having problems? Check out our Troubleshooting page to see if we have a known solution.