Apidays Helsinki 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/

Transcript

1. Customer Freight Booking APIs for Finnlines and for Grimaldi Lines, Short Sea Vesa Vähämaa Head of Group IT, Software Finnlines Plc and Finnsteve companies API Days in Helsinki on 29th 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 Customer ERP OR Cloud Service OR Package Software 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, get allotments, get trackings 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 specific Atlas API , Do Bookings, get allotments, get trackings https://grimaldi-group-cloudtest-agent.frendsapp.com/api/docs/api/atlas/docs/ui/index
7. Atlas Common APIs , 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. Frends IPaaS selected 1st 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 1st 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! 1st 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 2nd 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 3rd 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: sold goods 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: ClientId 123 PortOfLoading FIHEL API Agreement Line API User properties: UserId, Passwd, purpose, technival contact 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 devops process 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, LoadingPort PK, DischargePort PK, 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 data in 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. Frends deployment 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. Difficult to 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 (Frends side ) 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 bookingId for Allotment Change OR unitPk, bookingId for ShipmentItem Status 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 2 Customer 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