RESTful API Roadmap

In the current OneBusAway roadmap, we expect that the RESTful Mobile SIRI APIs (currently in use in OBA-NYC) will replace the existing "Real-time APIs" in the onebusaway-api-webapp project. However, the OBA "Discovery APIs" for static transit information (generated from a GTFS feed) will remain in use. Some of the existing OBA API's provide a mix of real-time and "discovery" information; these will be partially deprecated.

Below is a list of all of the current OBA API services, grouped by the degree of planned deprecation.A list of APIs to be added (i.e. SIRI services) follows after. Check out the OneBusAway REST API documentation for information about the OBA APIs as they exist today. If you're interested in the mobile SIRI API, check out the SIRI Web Service API page. If you're interested in how the SIRI APIs Elements and fields map to user-facing transit information, please see the SIRI Element to UI Mappings page.

##Deprecation vs Configuration## While there is general agreement that the exclusive use of standards-based API's for real-time information is a good goal, it is also recognized by the OBA community that a number of live deployments include the full OBA API, which is being used by a local ecosystem of app developers. As such, a short/medium-term approach to unifying the OBA codebase across a range of deployments is to make the elements described below as deprecated configurable. In other words, allow these elements to be removed by configuration actions taken at deploy-time.

Update 9-9-2013 - There is still open discussion for whether or not real-time data will be removed from the OBA APIs. The multi-region initiative has enabled the rapid deployment of the OBA apps to any new city who implements the core OBA server code. Currently, the mobile apps only support the OBA real-time APIs (not the SIRI APIs), and therefore all apps would need to be updated to the SIRI APIs before the OBA real-time APIs would be deprecated. Therefore, the below roadmap should be considered speculative until there is further agreement within the OBA community for the next steps forward.

OBA API's to Keep Entirely##

These API's will be kept in their entirety because they have no real-time information and serve purely "Discovery" purposes.

• agencies-with-coverage - list all supported agencies along with the center of their coverage area
• agency - get details for a specific agency
• route-ids-for-agency - get a list of all route ids for an agency
• route - get details for a specific route
• routes-for-agency - get a list of all routes for an agency
• routes-for-location - search for routes near a location, optionally by route name
• shape - get details for a specific shape (polyline drawn on a map)
• stop-ids-for-agency - get a list of all stops for an agency
• stop - get details for a specific stop
• stops-for-location - search for stops near a location, optionally by stop code
• stops-for-route - get the set of stops and paths of travel for a particular route
• schedule-for-stop - get the full schedule for a stop on a particular day
• current-time - retrieve the current system time

OBA API's to Partially Deprecate/Make Configurable

These API's will be modified to remove any real-time data. They are to be kept in part because they do provide some useful "Discovery" purposes.

• trip-details - get extended details for a specific trip. The ability to receive tripStatus information will be removed.
• trip - get details for a specific trip. The ability to receive tripStatus information will be removed.
• arrival-and-departure-for-stop - details about a specific arrival/departure at a stop. The ability to receive tripStatus, predicted arrival and departure times, and vehicle distance from the stop will be removed._
• arrivals-and-departures-for-stop - get current arrivals and departures for a stop. The ability to receive tripStatus, predicted arrival and departure times, and vehicle distance from the stop will be removed.
• trips-for-location - get active trips near a location. The ability to receive tripStatus information will be removed.
• trips-for-route - get active trips for a route. The ability to receive tripStatus information will be removed.

OBA API's to Entirely Deprecate/Make Configurable

These API's will be removed in their entirety because they serve no "Discovery" purposes.

• trip-for-vehicle - get extended trip details for current trip of a specific transit vehicle
• plan-trip - plan a trip (BETA) (DEPRECATE. Check out OpenTripPlanner if you're interested in trip planning).
• register-alarm-for-arrival-and-departure-at-stop - register an alarm for an arrival-departure event
• cancel-alarm - cancel a registered alarm

SIRI API's to Support or Add

Mobile SIRI APIs (ADD) - a set of APIs to retrieve real-time transit data (e.g., what time is the bus estimated to arrive at my stop? How far is the bus from my stop?) that were ratified as an official "Service Interface for Real Time Information (SIRI)" standard by the CEN European Committee for Standardization. These APIs were first deployed as part of the MTA Bus Time project, and they will eventually replace the OBA real-time APIs in the main OBA project.

These APIs differ from the standard SIRI specification since the mobile SIRI API is designed to be REST-ful and supports Javascript Object Notation (JSON) encoding as well as XML encoding. However, the forthcoming 2.0 version of the SIRI specification explicitly allows for these mobile/developer-friendly changes.

Here's a list of the existing SIRI APIs (see the MTA documentation for full details):

• VehicleMonitoring: real-time information about one, many, or all vehicles tracked by the system.
• StopMonitoring: real-time information about vehicles serving a particular stop.

The following SIRI API should also be added:

• SituationExchange: real-time information about "situations" (i.e. service alerts). The existing SIRI API includes applicable Situation information alongside VehicleMonitoring and StopMonitoring results, but there should also be an API to get just Situation information by itself.

For detailed information on how the SIRI APIs Elements and fields map to user-facing transit information, please see the SIRI Element to UI Mappings page.