Apidays Helsinki & North 2024 - APIs ahoy, the case of Customer Booking APIs in Finnlines and Grimaldi Lines by Vesa Vähämaa, Finnlines

Keynote 1: APIs ahoy, the case of Customer Booking APIs in Finnlines and Grimaldi Lines, ShortSea
Vesa Vähämaa, Head of Group IT, Software at Finnlines Plc

Apidays Helsinki & North 2024 - Connecting Physical and Digital: Sustainable APIs for the Era of AI, Super and Quantum Computing (May 28 and 29, 2024)

------

Check out our conferences at https://www.apidays.global/

Do you want to sponsor or talk at one of our conferences?
https://apidays.typeform.com/to/ILJeAaV8

Learn more on APIscene, the global media made by the community for the community:
https://www.apiscene.io

Explore the API ecosystem with the API Landscape:
https://apilandscape.apiscene.io/

1. CustomerFreight BookingAPIs
for Finnlinesand for Grimaldi Lines, Short Sea
Vesa Vähämaa
Headof Group IT, Software
Finnlines Plcand Finnsteve companies
API Days in Helsinki on 29
th
May,2024

2. Grimaldi Group
& Atlantic
Network
The largest in Europe
in combined ro-pax and ro-ro
segment shipping company
1
50
130
modern vessels
countries

3. With Finnlines
you reach all the
main ports
in the Baltic Sea,
the North Sea and
beyond
•Finland
•Germany
•Sweden
•Poland
•Denmark
•Great Britain
•Ireland
•Belgium
•Spain
•Estonia
LOGISTICS IS OUR BUSINESS AND PASSENGER SERVICES
STRATEGY:
MOTORWAYS OF SEA
- EFFICENT, EASY, RELIABLE, SUSTAINABLE

4. CARGO UNITS in RO-RO AND RO-PAX VESSELS
LORRIES with driver, TRAILERS, SELF-DRIVEN UNITS, CONTAINER ON TOP OF MAFIs
NORMAL MORNING AND EVENING IN NAANTALI-HARBOUR, TWO SAILINGS PER DAY

5. Finnlines
ERP
Grimaldi
Lines
ERP
Customer
API
Agreement
API User
Customer
Atlas API
Get Schedules
Get Allotments
Do Bookings
Get Trackings
API Access Management
Create API Agreement
for Customer
Maintain API Users and
User permissions
Get Admin User Access
CustomerERP
OR
CloudService
OR
PackageSoftware
REST JSON API User Connection
with https,apikey,api user/passwd, client ip-address control
API connections for freight customers to do bookings in Grimaldi Group, ShortSea
Customer Atlas API (PROD), Do Bookings, getallotments, gettrackings
https://grimaldi-group-cloudtest-agent.frendsapp.com/api/docs/api/atlas/docs/ui/index
Common Atlas API (PROD), Get vessel schedules
https://grimaldi-group-cloudtest-agent.frendsapp.com/api/docs/api/public/docs/ui/index
•Same APIs for all Grimaldi Lines and Finnlines Customers in Microsoft Azure Cloud

6. Customer specificAtlas API,
Do Bookings, getallotments, gettrackings
https://grimaldi-group-cloudtest-agent.frendsapp.com/api/docs/api/atlas/docs/ui/index

7. Atlas CommonAPIs , to get vessel schedules
https://grimaldi-group-cloudtest-agent.frendsapp.com/api/docs/api/public/docs/ui/index

8. This presentation is also
the story
from the idea,
to the solution proposal and
the implementation,
as well as
experiences of usages
HELSINKI- VUOSAARI HARBOUR
FINNLINES HQ
GATEHOUSE

9. Finnlines Integration Architecture for A2A, B2B Integrations
-REST API development/deployment tool selection in 2018
Finnlines started API
development in 2018.
FrendsIPaaS selected
1
st
Idea:
Let’s start using
REST API
technology

10. First External Atlas API-solution (MVP-version) was developed in 2019
Freight
Booking
Customer
Allotment
Vessel
Schedule
Customer
registration
Freight
Tracking
✓This 1
st
solution was only for Finnlines!
✓Only for certain contract customers and certain bookings
✓BUT we began to learn benefits of REST API technology more and more,
API journey started!
1
st
API
development-
project

11. Shipping line’s Ledger about permissions of shipment item
-Share shipment/booking and shipment related data to all kind of
trading partners and to authorities via APIs ?
We started thinking about what if we could share
shipment data for all kinds of B2B purposes
Booking Item /
Shipment Item
Customs
Authorities
Port
Authority
Stuffing Company
Loading
Stevedoring
Shipper
Vessel
Systems
Consignee
Shipper’s clients
Consignee’s parties
Discharge
Stevedoring
Truck
Company
Truck
Driver
Stuffed
units
gate&
stevedoring events
gate&
stevedoring events
Stowage position&
estimated discharge
time
Lorry driver(s) information
Initiate
Agreement Party
2
nd
Idea in 2020:
How to share
data?

12. •Must be possible to manage, which API Clients are using the
Atlas APIs and which API versions they are using
•Must be possible to manage API Dev-> Test -> Prod process
for each customer/trading partner
•Must be possible to manage different security layers and
different API user roles?
We started to thinking about API management software,
what if we had hundreds of API connections
REQUIREMENT: ATLAS API solution must be managed scalability when
number of API users and number of API swaggers are increasing
Number of API Users/ Organizations
Number of API Products/Swaggers and swagger releases
Max 10
Max 2
Target/Vision
Max >100
Max 30.50 API releases
3
rd
idea in 2020: How
to manage a lot of
API connections ?

13. Conclusion: “Permission ledgers” are required to enabling independent companies to interact trust way
with each others using APIs:
-This could be scalable solution for all trading parties!
Profit
Business
Business
Processes
Organization
Infrastructure
Profit
Business
Business
Processes
Organization
Infrastructure
Profit
Business
Business
Processes
Organization
Infrastructure
API layer
Shipping Company
API layer
Transportation Company
Stevedoring Company
API layer
Profit
Business
Business
Processes
Organization
Infrastructure
Manufacturer
Permission Ledger of
Shipment Item
Permission Ledger of
Operation Handling Item
Permission Ledger of
Consignment Item
Permission Ledger of
Goods Item
API layer
Interest trading
parties
Interest trading
parties
Key billable item:
shipment/booking item
Key billable item: consignment item
Key billable item: operation handling item
Key billable item: soldgoods item
IT Systems
IT Systems
IT Systems
IT Systems
4th idea:
Permission
ledger for APIs
is needed!
Interest trading
parties
Interest trading
parties

14. Solution Proposal in 2021
-New API Product and User Management System should be developed
-But it should be Grimaldi Group wide solution!
Atlas
APIs
Product and
User Access
Management for
Atlas APIs
With
Permission Ledger
Get APIUSER PERMISSIONS
B2B
Partner
(Customer/
Terminal/
Authority/
Other)
Customer/Shipping Company API
User connection with APIKEY
API Services
for Grimaldi Lines
Freight Booking system
for Grimaldi Lines
API Services for
Finnlines
Freight Booking System
for Finnlines
Create and maintain API User Permissions
PUBLIC ATLAS API with APIKEY
Shipping
Company
User
Important milestone
The API project was
launched & was
approved
by Grimaldi Group
Dev.team 1
Dev.team 2
Dev.team 3
API Developer
Customer Admin

15. Solution Proposal: Data model of API User Management with Permission Data
Shipping
Company
Client API Agreements
API Users
Permissions…
Shipping Company
Admin User
API Users
Allowed Resource Permission
Customer
Admin User
Allowed Parties
Agreement
Party
Booking System (Atlas)
Customer
Shipping Company
API Agreements
Possible Resource Permission properties:
ShippingLine,LoadingCountry,LoadingPort,
Vessel,ScheduleId, CustomerId, ShipperId,
BookingId, ShipmentNo, TIN, TinSeq,
UnitId, VinId, TruckId, DischargeCountry,
DischargePort, Consigneeid
API
Product
…
API Environment
(DEV/TEST/PROD)
API Admin/Developer
User
Allowed Traffics
(Business Units)
API Agreement Lines
Allowed Resources
Allowed Methods
Repository of
API
Connections
Sample of HTTP Methods
properties:
GET, PUT, POST,DELETE
Sample of Resources property values:
/v1/bookings
/v1/bookings/{bookingIdOrTin}
/v1/trackings
/v1/allotments
Sample of Resource permissions:
ClientId123
PortOfLoadingFIHEL
API Agreement Line
API User properties: UserId, Passwd,
purpose, technivalcontact info,
API Product, API Release, API Role
For stevedoring
companies/
terminals,
customs,
authorities,
other internal
systems
For b2b freight
customers
manages

16. Solution Proposal: Data Model for API Product/API Swagger management
-This is needed for controlling API devopsprocess and it makes easy to setup permissions for specific API User Role
API Product
Registered Resources
Registered Methods
HTTP Methods properties:
GET, PUT, POST, DELETE
API Release
API Products / API Swaggers
•Public Atlas API, Customer Atlas API, Authority Atlas API,
Terminal Atlas API
•API Key is defined in this object/level
-Release No, release Date
-API User Documentation
-API Release Notes
-API Swagger URL
Resource Settings
Examples:
ClientId
LoadingPort
API Environment
Example: Development, Test, Beta, Production
Possible Permission setting values:
ShippingLine,
ClientId,
LoadingCountry,
LoadingPort,
Vessel,
ScheduleId,
LoadingPortPK,
DischargePortPK, ClientId,
ShipperId,
BookingId, ShipmentNo, TIN,
TinSeq, UnitId, VinId, TruckId,
DischargeCountry, DischargePort,,
Consigneeid
Resources property values. Examples
v1/bookings
/v1/bookings/{bookingIdOrTin}/units/{unitPk}
/v1/allotments
/v1/schedules
Resource setting
defines, which API
attributes restrict
datain API
API Admin/Developer
User

17. API Admin/Developer
is registering API Products
First PRODUCTION version
was released in 2022
-Screenshots about API Product

18. Screenshot of API User Management system
-it is hierarchial: Agreement-> Users
It was developed by https://en.aavaerp.com/
software company
Shipping Company Admin User
is entering API Agreements
Customer Admin User
is entering API users

19. Demo web apps on top of Grimaldi Group Atlas APIs was developed also!
•Demo client apps(node.js) introduce
capabilities about External Atlas APIs
and help/speed up customers to
start utilizing them
•It is available both for Finnlines and
for Grimaldi Lines customers

20. Current Status:
Grimaldi Group in production
•About 1 million api instances monthly…
•It is estimated to increase 5 millions in 1-2 years… when new Extranet-system is rollout
to all Finnlines traffics (on-going now)
•About 100 api processes have been developed to production
•2 full-time inhouse api architect/api developer
•10 API Customers in production, 10 API Customers in testing phase, 2 port
operators in testing phase
•New digital services for Finnlines and for Finnsteve companies have been
developed, which are using APIs
•New Extranet, ShortSea B2B booking–system for Finnlines freight customers
•Self-service check-in mobile apps for lorry drivers
•Discharge tracking mobile apps for trailer drivers
•Helsinki Terminal Interchange area API-communication
•frontend apps, which is used for loading&discharge operations in Grimaldi Lines

21. Business Benefits: Efficiency, real-time, new business
1.It is important that solution can update and search up-to date information 24x7 in real-time, so that B2B
customers can also offer digital solutions for their own customers and subcontractors
2.Same API Interfaces are used also for all new Finnlines Digital Services!
•Example Self-Service CheckIn apps & kiosk OR New Finnlines ShortSea B2B Extranet Digital Service
3.”Self-Service” B2B Integration implementation. It is easy and fast way to open new B2B connection.
4.External ”B2B Cloud Services” and ”Package Systems” need common/generic interfaces, which work for
all B2B customers
5.Real-Time connections. It is on-line solution: to make Booking Request and get Booking Confirmation
6.New B2B Customer-case
•B2B customer connections can be enabled on Day 1, no more 1-2 months integration definition -project
7.New Traffic/Business-case
•B2B integrations can be started for new traffic on Day 1
8. New Terminal/Location-case
•Terminal connection to new Terminal TOS-system can be start implemented on Day 1
9.Future Development
•All B2B customers and terminals get benefit about new API development

22. ONE BUSINESS BENEFIT EXAMPLE!

LORRY DRIVER SELF-SERVICE CHECK-IN -SOLUTION
MOBILE APPS & KIOSKS
THE SOLUTION HAS BEEN BUILT ON TOP OF ATLAS APIs AS WELL ☺

23. Lessons Learned: External API design & develop & Test &Usage experiences
1.Backend system web services for API were not well documented and they have used for other purposes also,
so backward compatibility has been keeping all the time. This has made things much more complex to solve
2.Frendsdeployment has been fast and easy to do, but backend system web services for API has been complex
process to do deployments and test, a lot of dependencies
3.Old legacy business rules has been defined for old B2B integrations (XML,EDIFACT, etc), which are not needed
for API world. They have been still maintained in API side for supporting also old b2b integration solutions.
4.API customers are using APIs in different ways,they have different business processes and APIs try to support
them all. This is sometimes difficult. External APIs are required much more validation logic than for internal
purpose APIs
5.Architecture of API
•Decision to build bigger APIs or small APIs.
1.A lot of SMALL APIS: +Easier to maintain, +performance is better, -not so familiar for customers,
-bigger development work from customer side
1.BIG APIS: +more familiar to customers, -heavy to maintain, -performance issues.
6.Difficultto explain outside IT people the benefits of APIs
7.Compatibility that other BOOKING CHANNELS (not API) must be working also and they must work together
8.Same APIs are supporting two different shipping companies (FINNLINES and GRIMALDI LINES). Backend
business processes are different and mandatory data sets are different. This differences have been coded inside
APIs
9.IT and Business responsibilities are not always clear when new API customers are deployed to PRODUCTION
10.We have NOT built any customer specific API logics. This is important principle, same APIs for all customers!

24. ATLAS API Future Version Development:
Subscription of API Notifications
Subscription Type
Subscription SUBSCRIPTION TYPE, API KEY, API POST URL, HTTPS BASIC AUTH USERID,
PASSWD
TIMETABLE CHANGE API CALL
ALLOTMENT CHANGE API CALL
SHIPMENT ITEM STATUS CHANGE API CALL
SHIPMENT ITEM TRACKING CHANGE API CALL
Filter events based on
subscription and allowed
resource permissions
API User
Allowed Resource
Permissions
API logic (Frendsside )
Atlas API Product and Access Management
GET
Timetable
change event
Allotment
change event
Shipping Item status
change event
Item Tracking
change event
Standard/Common
API Notification Call
GET
API NOTIFICATION CALL to API URL WITH API KEY and JSON BODY (
API Environment,
API Product,
API Version/Release,
Event Type,
Effective datetime,
ScheduleId, vessel, POL,POD for Timetable OR
bookingIdfor Allotment Change OR
unitPk, bookingIdfor ShipmentItemStatus or Cargo Tracking Change
)

25. Vision of different ATLAS API swaggers usages
Port Operator
Atlas API
Vessel Atlas API Port Operator
Atlas API
Vessel-system to get
onboard units for Finnsirius-vessel
B2B ”booking cloud
service”
Customer 2Customer 1 Customer 3 Customer 4
Authority
Atlas API
FINLAND AUTHORITY
To
get
arrival
hazardous
units
Customer Atlas API
TOS-system to get Helsinki
to be discharged units
TOS-system to get
Travemunde to be
loaded units
Consignee Atlas
API
GERMANY AUTHORITY
to
get
departure
hazardous
units
Authority
Atlas API
Driver Atlas API
Self-Service Apps for
drivers
Cargo release-apps
for Consignee
Consignee
Drivers
Finnsirius
Customer 1
Customer 4
Finnsteve-
Stevedoring company
In Helsinki
LHG-
Stevedoring company
in Travemunde

26. Questions &Answers