Toteutus - Technical Documentation

Overview

Maritime MaaS API combines multiple ferry operators (transport service providers, TSP) and ticket systems under one API for MaaS operators to consume and on the other hand it provides the ferry operators with multiple MaaS operators just by integrating to a single API. It also harmonizes format of the transit data and especially the ticket data to make it easier for any MaaS client to connect and start using the API. It provides the MaaS operator easy to use API instead of time and money consuming integration work with all the TSPs.

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

Open

General architecture of the Maritime MaaS API

Maritime MaaS API is divided in to two different direction facing APIs:

1. 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.

2. 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.

Open

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.

Due to lack of support of customer types (or rider categories) and some other crucial missing fields Maritime MaaS API is using some extension fields in order to supplement the GTFS static standard. The model for implementing rider categories is heavily influenced by GTFS+.

Currently Maritime MaaS API follows the GTFS static (January 17, 2019 revision, https://gtfs.org/reference/static/ ) with some extensions that are documented.

The full specification of the Maritime MaaS API GTFS

There’s also an example feed available to help in constructing the GTFS feed.

MaaS API

MaaS API consists of a set of REST endpoints which are used by MaaS client to accomplish following tasks:

• 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.

Requests are authenticated using token authentication which MaaS operator will receive when it officially becomes an user of the API.

Current version of API documentation of the MaaS API

Ticket API

Ticket API consist of a set of REST endpoints which are implemented in the ticket system in order to make MaaS API able to call them. Ticket system is being called only when a booking is created and confirmed. Currently the endpoints are:

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:

1. Manual testing against the GTFS and API specification

2. Automatic testing against the provided end to end test suite

3. Further testing according to recommendations

Automatic end to end tests

Maritime MaaS API offers a test suite that automatically runs the happy path required for a successful ticket booking. It will make the requests end to end just as MaaS operator would do in the real life scenario. It includes following requests:

• Get all routes

• Get the information of one specific route (in case of capacity sales, also get departure information for selected date)

• Get seat availability information for the selected departures (capacity sales only)

• Make a booking (in case of capacity sales for the specified departures)

• Confirm the booking and check the ticket data

• Get/refresh the booking and check the ticket data

Download

Tests are distributed as a Postman Collection and you can download them here:

Open

You can download Postman here.

Import the file to Postman (instructions) and a new collection (Maritime MaaS API Ticket System) will appear to your workspace. It contains two folders:

Happy Path Open Ticket

Test suite for open ticket routes (capacity_sales=0) where no dates or departure times are set on the moment of booking.

Happy Path Capacity Sales

Test suite for routes with capacity sales enabled (capacity_sales>0) where departures times are queried from the routes and given as arguments for the availability and booking requests.

Variables

Test suites are configured with variables that are found under collection “Maritime MaaS API Ticket System” → “Variables”.

• base_url: base URL of the Maritime MaaS API

• route_name: Name of the route that is used in the test

• date: Date for the departures. This is used only in the capacity sales test

• capacity_sales: Value for the capacity sales. This has to match the value of the capacity_sales of the route defined by the route_name variable

Authentication

Test suite uses a collection wide Bearer auth. You can get this token from the Maritime MaaS team. Here’s a screencast how to set the authentication in Postman.

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

Open Ticket

Capacity Sales