Informations
Jobs
What is the article about?
Working according to a standard... really? Come on – software developers know how to build APIs. Besides, they want to stay flexible and have neither the desire nor the time to plough their way through some endless set of rules. And even if you've read them, that doesn't mean you agree with them. Fair enough. Nevertheless, there are a few challenges to overcome in software development, especially when working in autonomous teams and when you're dealing with business growth.
This post offers an insight into how we at OTTO came up with our own API Guidelines and implemented them successfully.
The challenge
"I don't see the benefits. This just slows me down."
"That doesn't work for me."
Sure, when we launched our API Guidelines initiative, we initially had to deal with reactions like these. However, as the discussion progressed, we quickly came to take a closer look at the common situation we currently face at OTTO:
- OTTO is transforming into a marketplace.
- the company is growing.
- we are developing software in numerous autonomous product teams.
If you're reading this you may be able to empathize with the challenges the situation entails, and have probably already experienced the immediate impacts and consequences in your daily work.
To be more precise, many people know OTTO as a retailer; in this dimension alone there are a lot of interfaces. And with the transition to an online marketplace, many more interfaces and marketplace partners are constantly being added. Of course, this is where we come in with APIs to provide business functionality. All this happens across the widest-possible variety of autonomous-working teams and different IT divisions. Let that sink in for a moment!
Incidentally, there are similar challenges on the market side: we're in the same boat as Spotify, Atlassian and Zalando, for example.
The insight
Imagine an API that provides access to a "list of product variations" and "a product variation". Which URI would you choose?
Figure 1: Quiz
Figure 1: Quiz
From a pure REST perspective, all these paths are technically correct – but each answer is different from the others. These solutions are clearly inconsistent.
And this is how things are in Product Development with numerous teams. Many of us develop APIs and all of us tackle it differently. To us it was crystal clear that API Guidelines are cool and as a uniform standard would help us a great deal. That said, we still had a long way to go to deliver easy-to-understand and uniform APIs, so we decided to get involved here.
The implementation
To develop coherent and consistent API Guidelines it's important to involve as many colleagues as possible from different teams to be able to take account of the wide spectrum of practical requirements. In addition, maximising collaboration and the right to contribute will secure greater acceptance in the structure and later implementation of the planned API. We relied on our internal prioritisation process to free up resources for a working group of this size. As soon as we'd done that, we held a kick-off that included joint topic definition, the formation of small groups for key topics, consensus on our working approach with the GitHub Project Board, and ongoing agreement via daily stand-ups.
In this phase, we also brought in a Technical Writer to shed light on the process. Was what we were outlining here easily understandable? Would a rookie understand all this too? After all, we are constantly aiming to publish documentation that will be easy to consume for all target groups.
Through close focus and agile processes, the working group quickly achieved results. This way, we were able to 'peddle' it directly to consumers within the organization, gather their feedback and incorporate this. We subsequently obtained the explicit commitment of the teams to use the API Guidelines in API design in the future, with the explicit proviso that the guidelines are a living document and can be expanded at any time.
In the interests of promoting overarching cooperation, we additionally announced reaching our milestones with a roadshow and also raised awareness of the API Guidelines beyond our own organization.
In this phase, we also brought in a Technical Writer to shed light on the process. Was what we were outlining here easily understandable? Would a rookie understand all this too? After all, we are constantly aiming to publish documentation that will be easy to consume for all target groups.
Through close focus and agile processes, the working group quickly achieved results. This way, we were able to 'peddle' it directly to consumers within the organization, gather their feedback and incorporate this. We subsequently obtained the explicit commitment of the teams to use the API Guidelines in API design in the future, with the explicit proviso that the guidelines are a living document and can be expanded at any time.
In the interests of promoting overarching cooperation, we additionally announced reaching our milestones with a roadshow and also raised awareness of the API Guidelines beyond our own organization.
The support
It's clear to us all that publishing a document and then simply expecting everyone to comply with it is somewhat unrealistic and condemned to failure. To help establish our new standard in the company and support teams in applying it, we introduced the new role of API Coach. Whenever required, experienced developers accompany the API development process end-to-end, right from the joint specification between the API provider and the consumers, through implementation, to go-live. This role was intended as a jump-start aid, for long-term regular use by the teams and as part of the ongoing exchange with an active API community.
Alongside hands-on support we developed a linter that can be used to automatically check the API specifications for guideline compliance. How cool is that?!
Alongside hands-on support we developed a linter that can be used to automatically check the API specifications for guideline compliance. How cool is that?!
Abbildung 2: Linter Ergebnisse
Figure 2: Linter results
What's more, we provide easy access to the guidelines via our API Portal which allows API consumers to see directly that we are working according to an API design standard and value quality very highly.
The impact
After more than two years working with established API Guidelines, we can now say from our own experience that using API Guidelines ARE a good idea. More and more teams are realising the benefits of working to a standard because they can use something they already have, instead of spending valuable time working out a unique approach for themselves. API consumers in particular explicitly request APIs developed according to the API Guidelines to ensure minimum friction on uptake.
High-quality, long-lasting and predictable APIs are more vital than ever, which means that we don't want to do without API Guidelines going forward.
Sharing is caring
You've made it this far and are now wondering, "so where can I find the OTTO API Guidelines?" We've placed them neatly in apublic GitHub project and they are also available via the API Portal. We warmly invite you to use the API Guidelines as a standard for your own API development – and encourage you to collaborate with us, exchange ideas with us and give us proactive feedback! It is possible that the guidelines will also be a major help to your daily API business and on our common journey towards consistent APIs.
Wanna be part of the team?
3 people like this.
0No comments yet.
Write a comment
Answer to: Reply directly to the topic
Written by
Birgit Bader
Senior Technical Writer
Similar Articles
COSTNovember 12, 2024How we used a simple trick to save USD 500,000 in data transfer costs
03Increased efficiency of cloud usage ✓ Cost reduction ✓ Migration to dual-stack IPv6 ✓ Find out more now!DevelopmentCloud
DominikSeptember 30, 2024Developer Hacks – Modern Command Line Tools and Advanced Git Commands
014In this article, you learn more about a modern development setup, state-of-the-art alternatives to classic shell programs, and advanced git commands.DevelopmentWorking methods
