API Advice

API Experts - Shipping APIs for Global Shipping

Nolan Sullivan

October 27, 2022

TL;DR

• Platformization efforts can start off as a single team mandate, but you need to figure out how to scale them into an org wide mandate to be successful.
• For larger companies with an acquisition strategy, an API platform can be the difference between a successful or a failed integration with an acquired business.
• Public API teams often evolve into having a DevEx mandate. Making users successful in using your API isn’t narrowly focused on documentation.
• For a good DevEx, focus on eliminating the need for any interaction with customer support.

Introduction

Could you explain what you & your team are responsible for?

I’m a Senior Engineering Manager of Flexport’s Public API team, which also goes by the moniker of ‘Developer Platform’. Those two things are related because the API platform serves as the foundational piece of our external developer experience. We’re a 2.5-year-old team, and we’re looking to greatly expand our scope to become the horizontal tooling provider for all the internal Flexport engineering teams who publish and maintain APIs, and enable them to give external non-Flexport developers a superior industry-leading experience.

On flexport.com, if you open the “Developers” menu item (opens in a new tab) – everything listed there is built by, or supported by my team in partnership with teams across our entire Technology organization.

APIs At Flexport

What are the key goals for the API platform team?

A key goal for the company is to become more API-first – as our Executive leadership has said, “The vision is to build the technology platform to make global trade easier. We will open up more and more capabilities for anybody in the world to use”; we are building the API platform for internal developers, partner developers, as well as 3rd party developers (opens in a new tab). That’s the strategic product vision my team seeks to achieve, so internal and external application developers can build on Flexport’s tech platform. I think this story will sound familiar to many companies: APIs will only increase in importance as a lever for Flexport’s future growth and scale.

A key goal for my team is to increase end-to-end automation for internal and external API developers, which will, in turn, increase API creation and adoption. We’re always thinking about ways that we can empower these engineering teams to expose their services externally, as easily and quickly as possible – while giving them access to the critical functionality needed to run a great API. That means taking care of everything from observability, telemetry, monitoring, testing, scalability and reliability, through to hosting developer portals, documentation, developer tutorials, code samples and OpenAPI schema creation.

What is the value of having the API Platform?

It’s all about increasing efficiency and throughput for internal teams, our customers and ultimately growing the business. Flexport constantly launches new product lines; APIs are critical for letting teams build products quickly and allowing partner developers to create engaging apps to delight our customers. Our API platform enables the internal teams to develop and maintain APIs faster, and deliver the consistency external developers deserve.

It’s worth mentioning that, because we are a large company, Flexport does make acquisitions and strategic partnerships with other tech companies. When we’re making an acquisition or building a new partnership, our APIs facilitate the integration and a frictionless customer journey.

You mentioned before that Flexport is ‘becoming’ API-first. Can you tell us about what Flexport is evolving from?

Flexport is a company that was founded in 2013. We started off delivering much of our service via web apps, though our public API usage has steadily increased over time. As our customer-base has grown, we’ve added more clients and partners who require enterprise-level platform integrations via API and want to embed Flexport functionality in their own software applications, which is why APIs have become a major focus as we seek to aggressively automate all aspects of the vast global supply chain which includes many operational tasks from origin to destination.

To seed the process of evolving from the monolith to a more flexible SoA/microservice architecture, API ownership was driven by my team as a consolidated initiative. That’s why my team directly maintains a portion of Flexport’s public APIs. That was good for getting started, though we sought out a more scalable solution for the long-term. APIs are merely a different interface for accessing the same set of entities and operations that Flexport’s web apps and internal APIs offer; therefore, each product team should own their corresponding APIs in a federated model. We’re nearly done with this transition; each individual product team is starting to own the REST APIs in their vertical domain.

Going forward, my team’s role will be to focus more on their enablement, maintaining consistent REST patterns, observability, automation, testing, monitoring and providing a world-class experience to our internal and external devs who call our public API; though when business priorities necessitate, we can still quickly mobilize our resources to directly implement new APIs on behalf of domain teams to help accelerate delivery. Our goal is public API feature parity with the functionality available in our web apps.

Flexport’s own application and platform integration developers are major consumers of our public APIs currently and we will continue to build and launch customer applications on top of our public APIs; there are a number of exciting apps and new APIs in various stages of development that our customers are going to love.

What type of tooling has your team rolled out to the teams at Flexport

Yeah, good question. Networking and security optimizations were some of the first things we tackled. Then we partnered with other teams to standardize infrastructure, identity management, and so forth. Next, we focused on building a comprehensive API best practice guide: from the networking layer, down to what the routes look like along with modeling new personas. We want to make sure the look and feel of Flexport’s APIs reflect REST standards. We also developed opinionated guidance about things like pagination, sorting, filtering, resource structure, URI, versioning and Documentation. We’ve launched Flexport’s Developer Portal (opens in a new tab), in addition to our API reference (opens in a new tab).

So now, these templates and guidance are all documented for Flexport teams, and we are turning our attention to making implementation as turnkey as possible. Self-service is our northstar; both for the internal Flexport developer publishing and consuming APIs, and also, for the external developers we serve. We have rolled out 24x7 public API service health monitoring with our API status page (opens in a new tab) and are proud to consistently exceed our uptime availability target.

Developer Experience

You mentioned your team has a larger DevEx mandate. How did you grow from API ownership to DevEx ownership?

This is a pattern I’ve seen at other companies I’ve worked at as well. It’s common to start with a public API enablement team that has a fairly broad charter. At my previous job, we were building a lot of those frameworks and platforms for the businesses, which the different business units and teams could all leverage, and the end goal is always to make sure that the APIs have a cohesive customer experience across all the different product lines. And then that goal naturally expands from cohesive API experience to cohesive developer experience across the whole external surface.

What do you think constitutes a great developer experience?

I’ve been professionally working on public API and developer platform enablement / DevEx for almost a decade. I’ve collaborated with a lot of developer advocates and partnered with many folks building incredible industry-leading developer platforms. One of the things that is essential to a great developer experience is frictionless self-service. In a given year you should not need to talk to a human being via phone or email in order to successfully build applications on a strong technology platform. You only have one chance to make that positive first impression. And if you say, ‘Hey, you must talk to a human being to get your account verified’, most developers won’t come back, especially if you’re not really a well-known entity. I’d also avoid having a paywall. There are metrics that show that having a paywall in front of an API will cause your developer conversion to drop significantly. I recommend using a rate-limited free tier for developers to use in order to increase adoption.

Another part of self-service is the documentation. You need to have very good and accurate documentation for developers (opens in a new tab). You should provide code samples, SDKs, example applications, and status pages (opens in a new tab). My opinion is that the best you can provide is a sandbox for developers to actually interact with live. But you should make an effort to provide documentation in various formats. Written first and foremost, but some people respond better to video tutorials. We want to provide API consumers self-service access to metrics and usage dashboards, logs, errors and other configurations across production and non-production environments.

Lastly, you want to make sure the surface area is consistent and follows standards. For me personally, when I start using an API and I can see that they haven’t implemented best practices, I will question whether the company is reliable. For example, if the API isn’t rate-limited then that makes me think that they don’t really think things through. So, make sure you are embracing those best practices from the beginning.

Improving APIs

What are some of the KPIs your team tracks against?

Of course we look at uptime, since availability of our services is table stakes. We then look at active users over a given timeframe, usually monthly or weekly for our business. We track the active users (MAUs), latency (p99, p95, p90, etc.), volume of requests, uptime availability and error rate for each endpoint, and also the emitted web hooks. Those are the most basic metrics that are universal across the teams. Every team may have its own additional KPIs that they care about as well depending on what their team’s specific business objectives are.

What are the main challenges facing developers building public APIs at Flexport?

Our public APIs are not quite at feature parity with our internal capabilities. Our push to automate API operations will help improve our API development velocity as we strive for public API feature parity.

On that topic, a lot of our tooling and processes around APIs are still more manual – multiple manual steps, reviews and synchronous activities are required to get an API exposed externally. That’s what a developer would mention as the primary opportunity. For my team, bringing automation to many different concerns, across such a large surface area of APIs is definitely a huge opportunity.

Another topic we are navigating is better defining the responsibilities of platform teams like mine vs. the domain teams that build the API business logic. Today it can be fuzzy, though for the most part ownership is clear. Who is responsible for latency, performance monitoring and load testing? How do we help domain teams even be aware of performance concerns and become more sensitive to it? Customer delight is our primary goal and we drive towards this relentlessly.

How about a developer integrating with Flexport APIs? What are their main challenges?

We frequently receive requests for enhancements to our API and developer platform experience, and due to where we are in our API journey, we get a lot of requests from customers to expose more functionality via our public API. As I said before, our APIs aren’t at parity with our web app interfaces and internal APIs yet. So that’s definitely the most common request, to expose more internal functionality via our public APIs; to accomplish this we need to work broadly across our Tech org.

API Architecture

If someone was designing their API architecture today, what advice would you give them? How would you approach using REST or GraphQL?

Yes, this is a good question, and one I’ve been asked ever since I joined Flexport and started managing APIs. What I would say is that there is no right answer, you need to build with your customer in mind to delight the customer and deliver high-value business impact. At Flexport we are working in freight forwarding; we’re the leading technology disruptor in the supply chain logistics space. While the sector is digitizing, the rate of B2B digitization may be slower than some B2C industries, say Finance & Fintech.

Many of our partners in the space have been operating for much longer than Flexport. We do not have customers asking us for public GraphQL right now. That may happen in the future, and if there was a compelling customer use case we would consider it, though for our current customers and partners, REST endpoints and webhooks satisfy their requirements. If you’re in a space that is catering to developers who are asking for it, GraphQL might be worth considering. At my previous company we had some GraphQL public APIs though the customer demand was overwhelmingly for REST.

Closing

A question we like to ask everyone: any new technologies or tools that you’re particularly excited by?

I’m curious about AR and VR. We have held a couple of hackathons and for one of those hackathons, I built a VR treasure hunting game. Flexport is a mix of people; some of us are from the logistics, supply chain and freight industry, while others have not actually worked in this domain. There are people at Flexport who have never had the opportunity to visit a working port, or been on a container ship. So I built a little VR game in 2 days so that people could visually explore those different locations. In the game, you are on the hunt for personal protective equipment (PPE) aboard container ships, since during that hackathon, we were at the beginning of the COVID-19 pandemic and Flexport via Flexport.org (opens in a new tab) was making a big push to ship PPE to frontline responders (opens in a new tab) where we raised over $8 million. You can play the game at eesee.github.io/justflexit (opens in a new tab)