Crafting a Future-Forward Approach to Sustainable API Design in an API-first Company

One of these days I have been asked “What does API-first mean in general and for fulfillmenttools especially?” and I have to admit: It is hard to answer this in one sentence or even a series of sentences. In our heads here at fulfillmenttools there are definitely pictures, ideas and paradigms and sometimes opinions about that topic – but the little wonder takes place when you try to apply these things across the board in the day to day business. 

Hence, I decided to write down a current state of work, a mere “snapshot” on how and why we are doing API design without saying “This is how you do it – period!”. It is supposed to be an insight to fellow engineers, architects, CTOs and people that are interested in the question: How do you design and run an API that is consistent on the one hand but also flexible enough to facilitate fast moving and evolving business targets on the other hand?

The conversation often starts with this question – followed by:“And what is the strongest API technology?”. It is not surprising that  the answers to these questions are as diverse as the people you ask. 

On the one hand, the typical product owner does not like vague definitions or goals for the API. They are difficult to evaluate and will probably be struck from the list at some point for that reason. On the other hand, a software engineer, who writes a connector against the very same API, would like to see clean paradigms as well as a consistent look and feel when actually using the API as it makes coding easier. Meanwhile, the one and only concern of people who run production systems seems to be the response times & number of failing API calls – despite the underlying business functionality or assumed usage. 

At least, there is one thing all of these groups can agree on: Excelling documenting the abilities and concepts of an API (or the product in that regard) is not the cherry on the cake anymore but a must have for API-driven tech companies. 

fulfillmenttools is part of the MACH Alliance. This brings another perspective to the above question: the “A” in MACH is for API-first. So how do we weave that requirement into our processes? How do we make sure that the access to our function via APIs is key when designing a new function? And how do we impose transparency in using our APIs to foster ease of integration?

Instead of going on and on talking about many more opinions, challenges and requirements from an API provider’s point of view, I want to present to you two of our current approaches. Although they work for us at the moment, please keep  in mind that these are just two of many more aspects. They are under constant review and adaption as we are operating in an ever changing agile environment.

It has been the second sentence I heard from my CPO back in the day when we started fulfillmenttools:

It was a learning experience from the past: When dealing with autonomous teams in different domains, the provided APIs tended to look differently and were of different quality. Knowing we would provide an API-first product with heavy focus on unified and comprehensible interfaces for the platform, the first step was to admit that we need to spend time and energy in that regard. 

In a ten person organization, this might be quite easy. But as our team grew, involving the whole team got too time consuming and inefficient, so we soon recognized that some kind of expert group was needed. The idea is not new and in other organizations these groups are called Guilds or Community of Practice. In our case we called this group the “API Brigade” which is cross functional in itself: It currently comprises product owners, architects, backend engineers and also frontend engineers. So instead of choosing just the people that in the end use the API, we decided to involve business and architectural stakeholders which resulted in a clean, more concise approach. A benefit is that decisions that are made  by that brigade reach the teams and the engineering which in the end is accountable for bringing the decisions to life. 

Nobody likes too many meetings – and bottlenecks are even worse from a company’s point of view, especially in a growing, agile organization. The primary mission of the API Brigade is to enable the teams to make the right decisions for 90% of upcoming questions by themselves. But it only meets every two weeks for an hour. Therefore, the development of a mighty weapon for the day-to-day work of decoupled teams became necessary. In our case, it helped a great deal to just write rules down in a guide, which is in fact also common practice in other organizations. The magic in that is actually not the writing of the rules – but to make sure the rules are followed by the people in their day-to-day work. 

We decided to put the power to ensure things are done in the hands of the engineers. At fulfillmenttools, every engineer (or actually every team member for that matter) is encouraged to put not only business related topics but also technical or organizational issues to backlogs, refinements and in the end to the team board. This makes technical issues first-class citizens whenever the question “What’s next?” arises. This approach keeps a high focus on technically clean solutions and avoids limping behind in not very tangible topics – such as the API access to business functionality.

Another aspect that we encountered frequently in the past is the question: 

The answer is: There is no version – and still we are able to do dozens of releases & changes to the API every day without breaking integrations. Not surprisingly, this yields raised eyebrows and shaking heads. At least before we explain our approach, but let’s not get ahead of ourselves.

First, let’s take a step back: When you provide an API to a product which is used by developers outside of your organization, part of the deal is that implementations (clients, services, you name it) do not break. Or the other way around: The API has to be stable from a semantic point of view. In order to provide that, we could release versions of an API. The API in such a version is “fixed” and it never changes. Unfortunately, this contradicts the idea of a growing platform, growing products and their features, because (especially using an agile approach) the first iteration of a feature should bring value. But sometimes this provided functionality needs to change or must be extended. How does that work together with an agile continuous integration process? From where we are standing: Not very well.

In order to have an API “from one mold” (see above), keeping the ability to develop agile and bringing value iteratively and in a timely manner to our customers, we decided on a versionless API. This means it is constantly evolving and there are rules to this evolution, which are described transparently in our documentation. When a developer is aware of these rules it is not hard to follow them – making the developed solution robust and more stable.

Besides the things that we consider “non-breaking changes”, we decided to introduce Alpha, Beta and GA versioning per endpoint or model – again with a fixed set of rules to those labels. For instance, with providing an Alpha Endpoint we already give a preview to our partners and customers about currently developed features – looking for feedback and insights from a developers’ perspective for example. The deal is: Such an endpoint might change semantically at any time without any warning. Meanwhile, Beta endpoints are much more stable and could be used in production if desired: A change here must be communicated to our partners beforehand. 

We actively aim at limiting the time of Alpha and Beta endpoints to make the better part of our API Generally Available (GA). Does GA mean the API will never change in the future? Of course not! Again “non breaking changes” can and most likely will be applied, such as adding parameters, subresources, etc.

Having Alpha & Beta flagged endpoints plus the list of non breaking changes allow us to develop our product API-first without the hassle of frequent versioning.

Working in an API-first company is not always easy- especially because of the focus you are obligated to adhere to without having the benefit of “directly sellable outcomes”. However, we at fulfillmenttools strongly believe in a product that does not only comprises feature after feature but that also comprises modern, state of the art technology and accessibility – like an API.

Processes like giving autonomy to engineers and demanding accountability for their decisions as well as tools like putting different release states to a versionless API helped us to grow, stay technically in the lead and provide an API first developed platform. Is this always fun? No. Is it necessary and worthwhile to have such a strong non-functional focus on API? Yes, by all means.

What are your experiences with providing an API? What challenges did you face and how did you overcome problems on tooling and organizational level? We would love to hear about that!