Maersk is a multi-billion dollar Danish giant that specializes in container logistics. The company has previously experimented with building its own APIs for both internal and external purposes, but — as we’ll see — has faced a fair few issues.

In this article, we’ll look at Maersk’s API and digital transformation journey, and discover why the company is now focusing significant efforts on web APIs and smart API management tactics. To do so, we’ll follow the talk given by Dave Holliday, Product Owner of Maersk’s API Management Platform, at the 2019 Nordic APIs Summit.

Maersk and Digital Transformation

Dave starts his talk by explaining why digital transformation is important to Maersk. To do so, he introduces the status quo for modern-day supply chain tracking: the EDI 315.

The EDI 315 Status Details (Ocean) document is a message generated every time a container’s transport status changes, such as when it’s loaded onto or discharged from a shipping vessel. These messages are then distributed using transfer protocols like FTP, SFTP, and AS2.

The issue, says Dave, is that these “hideous” messages are hard to consume, and expensive to develop against for both Maersk and its customers. Take a look for yourself:

Instead, Dave (along with others at Maersk, evidently!) believes it would be much more convenient if we could express this information as a simple JSON object:

{
"move": "gateIn",
"time": "2019-10-2T08:28:00Z",
"carrier": "maersk",
"shipper": "party A",
"consignee": "party B",
"port": "rotterdam"
}

Not only is this format significantly easier to understand, but it’s also much easier to develop against. And ultimately, it being easier to develop against makes it both cheaper and faster to develop against. This, of course, is the value of digital transformation.

Mistakes in Maersk’s API Journey

According to Dave, Maersk’s foray into the world of APIs was originally inspired by the desire to improve customer experience on the Maersk.com website. By embracing an API-driven microservices architecture, they were able to build web applications for purposes such as tracking, booking, and schedule management with ease.

By the time these internal APIs were in place, customers also began to mention APIs and their benefits in the world of business. Naturally, Maersk’s response was something along the lines of —

Actually, we’ve got some APIs! How about we just share them with you?

Eventually, Maersk opened up access to their internal APIs, without really appreciating what it takes to build a proper externalization of those APIs. This single faux pas led to a lot more mistakes down the road.

No Developer Portal

Since Maersk didn’t originally set out to build customer-facing APIs, they had no developer portal for a long period of time. This meant customers had to be onboarded on a case-by-case basis and probably created many more support headaches than necessary. The solution to this issue is pretty straightforward: create a central portal for users of your APIs — but more on that later.

Failure to Use Standards

One of the first pieces of customer feedback on Maersk’s Schedules API — which allows customers to find out when Maersk can ship between two locations — was that it used Maersk’s proprietary geoIDs to refer to locations, making it difficult to use. Instead, locations should have been represented using UN location codes. As key learning, Dave says that when we look at externalizing APIs, we should always embrace industry standards to make the APIs interoperable and easy-to-consume.

Limited Functionality

Customers that used Maersk’s early APIs soon wanted to integrate the services into their own systems. Oftentimes, this meant they would need to request dozens, hundreds, or even thousands of containers at a time. However, Maersk only supported requesting one container at a time. To avoid similar issues with external APIs, it’s crucial to think closely about how customers will use them.

Excessive Firewalling

At one point, some customers were unable to access Maersk’s APIs at all. The cause was an excessively stringent firewall, which ended up accidentally blocking all traffic from Amazon Web Services IPs. Once again, the learning here is to be conscious of how (and where) customers will use your APIs.

No API Keys

In building their first APIs, Maersk didn’t appreciate the importance of API keys and other security measures. When these APIs were eventually released to customers, Maersk quickly realized that they couldn’t work out who was calling their API, leading to a frenzied effort to implement API keys. Of course, enforcing these keys was a breaking change to the API, which led to lots of conversations with consumers. The solution to this is thinking about how you go to market with your APIs, in order to ensure massive changes (especially breaking ones) won’t have to be made immediately.

The Crucial Area of API Management

Dave sees API management as one of the most crucial areas of Maersk’s API journey. This starts with an internal management platform, which should help to meet the technical, organizational, and business goals of the company in several areas:

• Discovery: The platform should help to avoid duplication and enhance the reuse of APIs. This is achieved with easy discovery of existing APIs.
• Support: The platform should track who built each API, where the codebase is kept, what stack was used, how it is tested, and how support for the API is provided.
• Proxies: The platform should enable seamless deployment of API proxies, in a playground and through higher environments.
• Data: The platform should enable data to be collected, monitored, and analyzed for business purposes. For example, 404 errors in the schedules API (Schedule not found.) could help to identify new routes for Maersk to service.

And for Maersk, there’s the external API management platform, which includes the following:

• Discovery: The platform should help customers find the APIs they need.
• Test: The platform should enable customers to quickly and easily test APIs.
• Monetize: The platform should enable monetization for some APIs.

Final Thoughts

It’s easy to make mistakes when rolling out an API platform, especially one born from the spontaneous externalization of internal APIs. In this case study, we’ve seen just some of the hiccups Maersk had when first adopting APIs, and how they paved the way for Maersk’s current-day focus on API management. With both internal and external flavors, Dave’s current API management strategy is designed to ensure APIs are as self-service as possible and create as few headaches as possible!