How an API-first approach is shaping the future of Zonos

Ever wonder what it means to be an API-first company? Read Zonos’ VP of Engineering, Andrew Spencer’s take on how an API-first approach is shaping the future of Zonos.

Zonos is an API-first company. There is a lot of information packed into that short statement. So, what does it really mean? This blog will break down the concept of an API-first company as demonstrated by Zonos.

If we assert that Zonos is an API-first company, it follows that our APIs are the primary strategy through which we achieve our mission of creating trust in global trade. Tactically, this means that we must take a company-wide API-first approach to everything we do. As we consider the needs of a customer, we first ask, “How can our APIs meet the customer’s needs?”

To better understand what it means to be an API-first company, this blog will discuss the following:

• What is an API-first approach?
• What are the benefits of an API-first approach?
• Why is working backward effective?
• What is the engineering responsibility?

What is an API-first approach?

The API-first approach starkly contrasts the code-first approach, where a team begins by designing the application’s functionality, writing the code, and then adding APIs at the end of the process.

At Zonos, building software using an API-first approach means designing solutions around an API, rather than coding an application and adding an API later. This means our APIs are paramount and products in their own right; we design them with an intense focus on the customer’s needs, and we clearly document and architect them before writing any code.

The benefits of an API-first approach

The API-first approach helps to establish the following mindset:

• We understand that our APIs are the primary interface for our customers, and therefore view them as our public deliverables.
• Documenting before writing code gives us the opportunity to reason, discuss, refine, and communicate our objectives with our teams and stakeholders to create a better end product.
• As we focus on the needs of our customers, we understand how best to design APIs that meet those needs.

This mindset places our APIs and customers first and is critical to establishing a foundation where everyone at Zonos is responsible for customer success.

Our reputation (and retention rates) hinge on how we honor our commitments to our customers. Our APIs are contracts. We are committed to fulfilling those contracts, and our customers rely upon them. And since it is much easier to change the underlying code than the API contract, it’s important to design and document our APIs first so that they can undergo a refinement period through an API design review. This collaborative process is key to creating great APIs.

It’s easy to see how an API-first approach puts the focus on being responsible for the customer’s success. Creating the API before coding ensures that we are creating the most accurate and valuable product in an efficient manner, but efficiency isn’t the only benefit.

Development teams can work in parallel

The API-first approach involves establishing a contract. Creating a contract between services that is followed by teams across an organization allows those teams to work on multiple APIs at the same time. Developers do not have to wait for API updates to be released before moving on to the next API. Teams can simultaneously mock test APIs and API dependencies based on pre-established API definitions.

Reduces the cost of development

APIs and code can be reused on many different projects. Under the API-first approach, if a development team wants to build a new application, they don’t have to start from scratch, saving time and money. API-first design also allows most problems to be solved before any code is even written, which helps prevent problems when it is time to integrate APIs with applications.

Increases the speed to market

Much of the process of building APIs can be automated using tools to import API definition files. We start by generating the core types, definitions, and schemas; with those files, API tools such as API documentation, software development kits (SDKs), and mock APIs can be auto-generated. Automation significantly speeds up the development of APIs and applications.

API-first also makes it possible to add new services and technologies to applications without having to re-architect the entire system. Zonos must ship features to production quickly to remain competitive in the ever-changing cross-border SaaS market. It is easier to eliminate technical debt in the underlying code than to migrate customers away from a poorly designed API.

Ensures good developer experiences

API consumers are most often developers, and developer experience (DX) can make or break the success of an API. The API-first approach ensures that the developer experience is positive because a well-designed, well-documented, consistent API is easier to learn and reuse. This also increases the speed of implementation. These benefits are all inter-connected!

Increases long-term success

An API-first approach allows for rapid prototyping and iteration, which means that we learn more quickly what works and what doesn’t. Like Eddison’s 1,000 failed attempts before creating the lightbulb, API-first means we fail fast and move forward with a better understanding of how to achieve success. API-first increases our long-term success by ensuring that APIs are reliable, consistent, and easy for developers to use.

Why is working backward effective?

In 2015, I had the opportunity to redesign the ecommerce site of a popular consumer brand. I evaluated various key performance indicators (KPIs) related to the existing system, and it was clear where the biggest improvements could be made:

• The desktop conversion rate was substandard.
• The mobile conversion rate was abysmal.
• The percentage of mobile traffic was rapidly increasing and would surpass 50% of total traffic within the next 12 months. Because of the abysmal mobile conversion rate, most of the traffic being mobile was not ideal.

Given the data, what would create the most value for users? It was obvious: fixing the problems with the site’s mobile user experience. Therefore, I took a mobile-first approach to redesign the site. This meant that all of the designs, architecture, APIs, etc. first considered the mobile experience. This was backward from the traditional approach at the time, which focused first on the desktop experience, often leaving the mobile experience as a clumsily bolted-on afterthought with poor conversion rates. The mobile-first approach also required more effort up front—it was not the easy path. A new architecture was required, new APIs would need to be written, and multiple designs were required for every breakpoint.

The mobile-first approach resulted in a significant increase in mobile conversion rate. The new architecture also yielded impressive gains in desktop conversion rate. The approach was successful because it identified how to create maximum user value and focused the entire approach on providing that value. It created the right mindset from the beginning. Likewise—though it may feel like working backward—an API-first approach creates opportunities to identify overarching issues and then build a foundation to correct those issues.

What is the engineering responsibility?

The API-first mindset has and will continue to lead Zonos to success, and engineering plays an integral role. It’s our responsibility to always maintain the API-first mindset. This means that we’re constantly asking questions that keep the focus on our APIs, such as: “How can our APIs meet the customer’s needs?” It also means that we always respond to questions about features and functionality with a link to our API documentation. If the documentation doesn’t exist, then we create it—working together on cross-functional teams to ensure that Zonos has stellar API documentation.

Resources

• Understanding the API-First Approach to Building Products