What is the “API-first” approach anyway?
It means that you start with writing the API first. Simple, right? Now, seriously…
This photo by Matt Howard on Unsplash
What is the “not API-first” approach?
As a developer, a product manager gives you a presentation with screens and interactions. Based on this presentation, you then go to design your software. You probably need some APIs for the clients to talk to your service, but these would be a by-product of your work.
For example, let’s say a product manager provided a presentation describing a TODO list. Based on this presentation, you would define what APIs you need (add task, remove task) in order to implement this specific product. Your API could turn out to be something like this:
What is the API first approach?
This photo by Say Cheeze Studios on Unsplash
The product manager, with the help of the developers, defines the capabilities of the product. These capabilities are then formulated as API. That API is a product on its own.
Specifically, this API would then allow you to deliver the UI (which we can think of as default UI) that the product manager wants to provide to the end users.
Considering the previous example, a product manager would define the capabilities of a TODO list while considering various use cases beyond the immediate need and comparing with APIs provided by the competition. These capabilities would then be formulated as an API that anyone could use. In this case, that API should be something like this:
How is this different from the previous API?
Date created and updated were added
Ability to add multiple tasks in a single “add all”
List was added with filter capabilities
Events were added
Now, obviously you could think of more features such as changing content to RichText, but specifically adding the above capabilities doesn’t force the product to support additional features as part of the UI (like RichText would require), but they do provide capabilities beyond what is required just for a simple TODO list.
Why would you want to consider an API first approach?
In short, while it seems to take more time to design these APIs, in reality it can actually save you a lot of time. It also allows the developer community to extend your product far beyond what you as a company have time for.
Let’s talk about the process that Wix went through adapting API first.
The age of private APIs
This photo by Annie Spratt on Unsplash
When you don’t do API first, then most likely your APIs are “private”, and that’s exactly what it was like for Wix a few years ago. A developer would get a task, see what new APIs they need to add or update and go for it.
Isn’t this what everybody does?
Well not everyone, but it seems to make sense. Until it doesn’t, because:
API becomes a mess over time, since it’s a by-product of your work.
Other developers in the same business unit have a hard time understanding the API when they need to use it.
Developers from other business units can’t understand it, which means integration becomes a very challenging process.
Developers from outside Wix obviously cannot use your API at all.
So what changed?
Wix decided to start a process known internally as “platformization” (Amazon decided to do this years earlier in 2002).
All services should have public well documented APIs which should be used both internally and externally by 3rd party applications.
And that was it right?
Wrong. This is a huge change requiring technological and process adaptations.
We need some tools
This photo by Zoe Schaeffer on Unsplash
Here is a partial list of the tools that Wix needed to create as an infrastructure in order to enable the API first approach.
Standard way of doing authentication and authorisation. Both internal and external clients should be able to use it.
A descriptive language in which you write your APIs, protobuf was selected for that purpose. The usage of this descriptive language is the basis for everything else. Wix also extended the language with many annotations. For example, annotations that allow additional validations such as length and format validations, ones that configure documentation, and much more. To provide more clarity, here’s how a TODO list task contract would look in proto. The validations such as wix.api.format and wix.api.minLength are custom annotations created by Wix.
An automatic documentation tool, any API written automatically gets documented internally.
Auto generation of client code for multiple languages, this includes service to service (RPC) calls and client to service (REST) calls. Protobuf has this out of the box to some extent, but Wix extended these capabilities.
An extension to the code editor, which ensures the API definitions are according to the standards and breaks when this isn’t the case.
The tools are not enough, some serious mind shift is required
Writing tools and libraries is often much easier than changing the organizational culture. Here is a partial list of practices Wix had to adopt:
Designing the API first :) Kinda obvious, but you know…
Defining standards for what a good API is - over time a forum was created to discuss dilemmas and build an ever growing guidelines document.
Actually making sure the APIs are in accordance with these standards, which requires that every API would be reviewed by a person who’s had expertise with these rules (known internally as an API master).
Adding a tech writer into the development process, needed to review the APIs at the beginning making sure the terminology is correct. Write the documentation and release it.
But we have something and it’s working
Ideas are great, but in reality employees (at least some) tend to object to such changes. This is one of the arguments, the current process is working and we deliver features, why change it? It takes time for the system to understand the huge value.
But we are going to spend a lot of time on it
Yes you are. But it’s worth it because you save time on integration and allow 3rd party companies to use your APIs.
So what is this “huge value” in all of this?
Apart from the fact that integration between teams can be done without talking to each other, as opposed to processes that take months trying to support some bad and unclear API, there are many success stories.
Taking the TODO list as an example, here’s what external developers might be able to do with the API:
Send notifications for tasks that are stale for too long, either by listening to events and saving the data on some other DB, or via calls to a list with filter for tasks not completed and created X days ago
Copy a TODO list by using list and bulk add
Collect user’s TODO tasks into some big data table and get more insights by listening to the events and copying the data over.
eBay plugin for Wix stores, a success story
Wix wanted to allow our users to sell their products, listed on their websites, on eBay too. In short, Wix has store capabilities where you can define products and sell them on your site. The requirement was that with a few clicks you would be able to also sell them on eBay.
Developing this capability would take months of work for many developers, instead a 3rd party company (Inkfrog) that already had integration with eBay was quickly able to integrate with Wix via our public well documented APIs. They were able to:
Read the products and create a UI that allows users to publish to eBay
Create an order in Wix when a sale is made on eBay
Update tracking number in Wix\eBay when a tracking number is added to eBay\Wix.
And Wix has many success stories just like this one.
Conclusion
API first is a good approach that allows easy integration both internally and externally. However, it requires technological tools to assist the process, a mind shift of the employees, and the understanding that over time this will provide great value for your company.
This post was written by Oded Apel
For more engineering updates and insights:
Join our Telegram channel
Visit us on GitHub
Subscribe to our YouTube channel
Comments