...
The project itself is open source and it’s licensed under MIT license. The repository can be found here: https://github.com/City-of-Helsinki/maritime-maas
General architecture of the Maritime MaaS API Maritime MaaS API is divided in to two different direction facing APIs:
The actual MaaS API which is offering REST endpoints for MaaS operators to get ticket options (routes, schedules, ticket types, etc.), purchase the ticket and perform other actions on the ticket.
The Ticket System API is handling the communications between MaaS API and the transport service providers or in other words the ticket systems. Route, schedule and ticket type information is provided by TSPs via a GTFS Feed which is read by the API. Ticket System API is a set of REST endpoints implemented in the TSP which are requested by the API as a result of corresponding request by the MaaS Operator.
.png?version=1&modificationDate=1620734906122&cacheVersion=1&api=v2)
General flow diagram of the API
...
GTFS Feed
Transit data is shared via General Transit Feed Specification (GTFS) feed which is served by TSP. It contains all static and semi-static information about the routes, schedules, fares and additional metadata. Standard way of describing transit data makes this API prepared for the future and Transport Service Providers are ready for serving their schedule information to other systems as well.
...
Currently Maritime MaaS API follows the GTFS static (January 17, 2019 revision, https://gtfs.org/reference/static/ ) with some extensions that are documented.
...
Get routes
Get schedules
Get departures
Get ticket types
Get seat availability information
Purchase and display ticket
Refresh ticket details
All the booking options are saved from the GTFS feed and MaaS API is capable to serve all the transit information even without a working connection to the Ticket API.
...
Endpoint | Description | Parameters | Return value |
|---|---|---|---|
POST /bookings/availability | Returns the seat availability for given departures |
|
|
POST /bookings | Creates initial reservation. Holds the tickets but no payment is made yet. |
|
|
POST /bookings/:id/confirm | Confirms the reservation and user may be billed. |
|
|
GET /bookings/:id | Returns (up to date) booking information |
|
|
Requests to Ticket API are authenticated using token authentication. Ticket system will provide MaaS API with a token which it uses to make authenticated requests.
Current version of API documentation of the Ticket API
Testing
Testing the integration of the MaaS API and Ticket API should consists of multiple steps including:
...
| Widget Connector | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
|
Running the tests
Here are two screencasts showing how to run the end to end tests both for open ticket routes and capacity sales routes
...