10 June 2022 / 0 min read
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:
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 API-first approach helps to establish the following mindset:
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.
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.
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.
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.
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!
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.
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:
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.
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.
Andrew Spencer is the Head of Engineering at Zonos. During his career, he has helped many startups innovate and scale by establishing solid technology foundations. In the ecommerce space, he has built technology to support 10x year-over-year growth, and scaled architectures to achieve nearly half a billion in annual revenue. Outside of work, Andrew loves spending time with his family in the great outdoors, and in his spare time he can often be found exploring the beautiful landscapes of Southern Utah.