RESTful API Roadmap - Hillsborough-Transit-Authority/onebusaway-application-modules GitHub Wiki

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.

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.