The difference between API first design and API first

API first holds a special meaning for me. When I first met the Australian Axway team at the 2015 APIdays (learn about APIdays 2019 here). (I was launching my first API portal with another company, Axway was talking about API Gateways). I noticed that all the Axway staff was in {“API first”} t-shirts. Immediately I was impressed.

And it was not long before we exchanged t-shirts. I am a big fan of the {“API first”} logo. I believe the APIs first thinking is fundamental for changing towards a digital mindset. Getting back to my views. First, there is a big difference between API first design and API first, they are equally important, but they are often confused.

API first design

API-first design is not the subject of this blog. It refers to a new method of creating APIs where unlike traditional development processes, an API was designed around the capability of a (backend) system. This old method is comprised of how more features, methods, and capabilities can be created. The better the API (design) was at that time.

With the new API-first design method, we start with the look and feel of an API. We also look at what the users of the API should expect. For example, when I released my first SMS API, the API was designed to give developers the capability to have their apps send a quick message, as such the design looked something like*:

{“to”:”0402991234″ , “body”:”hello, world!”}

This invoked different APIs and functions towards the backend, but we obscured this, by using an API Management Gateway, a large part of the development was spent on making the complex simple. API-first design often comes back to this. This having a customer (app developer) in mind and making it easy and clear for him/her (he/she wants to send a message to a number) in the design of the API, rather than proving how brilliant someone can be in making things very difficult. Tools like API Builder allow for an API-first design and allow you to craft the most loved APIs based upon this principle.

*There are other methods and more to the design of this API, but I am not going to explain the full design of the SMS API here.

API first

The confusion of API first is that it also impacts the design. However, it’s not (at least as part of my opinion) related to the API design. But, rather it applies to your solution design, start with the API first and work on the rest later. The reason why new cloud applications often go for this approach is that the end product will get a very modular base. You are working on the base of Lego blocks, which combined can make different outcomes.

Again, it’s easiest to explain the API-first approach by using some examples. Building up a SaaS service/application, it’s obvious to start with an API-first approach like Axway’s Syncplicity offering. The next example of creating an application for registering annual leave days. I am using the examples to illustrate what the advantages would be if we would design such a leave register solution by taking an API-first approach.

Syncplicity

Syncplicity has built up its collaboration software by taking an API-first approach. The basics of storing and retrieving files are all API based. The synchronization and richer functions are also first defined as APIs. Syncplicity can still use design methods like human design thinking. These don’t define a set of web pages, they define a set of functions, which will become APIs.

For instance, to share a file with an unknown user, would be a function like: “as a Syncplicity user I want to invite new users (by name and e-mail address) to the platform so I can share content with them” and “as a syncp user I want to share a specified document with another user, so I can collaborate with them.” These functions would become composite APIs like /create_user and a body with {“name”: “Harold wiegers,” “e-mail”: harold@apiguy.net} the share document API will do the function of creating the link and can use the same input.

Good news

The good news is, those functions have become the famous Lego blocks and can be reused for different functions. This is where being SaaS applications excel. They might have been initially designed for a non-relevant function but because they use Lego building-block functions, they can be quickly transformed in different functions that have a large business value which wasn’t intended at the start of the design.

The traditional design would have been based upon creating a database with entries of users, web pages that allow users to be added, and other design functions that create purpose-made solutions without any scope creep! By starting with databases or by starting with the UI, people have found out it doesn’t scale, if there is an app needed, you need to go back to step one.

By starting with an API, you create a pool of reusable core capabilities, which can grow rapidly in an expanding SaaS service. The consequence of starting API first, all functions are becoming APIs, 10 years ago, nobody needed the “invite a user” API, and there was no business case for creating this API, it was purely a design method.

By now, people are automating everything, and then invite a user API is widely used by the web page, android app, or by a provisioning system adding new employees in an automated way.

Another example

Another simpler example. Let’s imagine we want to get rid of the annual leave request form, and we will make a web application that allows us to put in annual leave requests. We have multiple choices on how to go about, but one thing is sure, “as an employee I want to submit data for leave days, so my leave data get registered.”

Again, we could start the design with a web page. This is where users can request info, and we structure a database with leave requests or calendar data. This way of designing would get us exactly what we needed: a tool to request annual leave days. The alternative for designing the leave request application is to start with the API. We would define the functions and create API calls for them.

Random example

We can find a random example for such an API with a google search something like the Xero one. We would work on the other use cases, which would all become API methods. After we have crafted the APIs, we would connect them to a database. We could give the API specs to the UI/ UX teams, who would easily create a front-end web page. The remark of many people will be “but we don’t need an API to request annual leave, that is wasted time, and it is dangerous to open it all up.”

However, creating solutions based upon API first, you don’t design it for the sake of the API. However, in 90% of the cases, the API will be reused somewhere somehow. With the leave request application, maybe nobody is waiting on this API, but imagine how good it would be if your consultancy team had planning software which considered when people requested annual leave, just to give one example!

Essentials

Essentially, if we would start our leave request application design with the API, we could easily grow it (independent on the UI or database). This will allow for whatever we want it to be because we focused on the API the application has become modular and easily changeable. We are set up for success with our new application.

Transforming towards digital business, more functions will become automated, to make employees empowered to do their job (rather than filling out Xls forms). The key to designing those digital functions is to start with the API of that function, once it is there, the rest will follow! API first is key for digital transformation and therefore I think we need to get it right!

Do you have a function? Application? Are you convinced you don’t need an API, comment below, and hopefully I can change your mind! Keen to get started with API first or API-first design? Write down your user stories and start crafting your API. There are many tools available I recommend giving Stoplight a try. Learn more in this Spotlight interview here.