DX, API Design & Documentation

API design is where culture and tech meet each other


API stands for Application Programming Interface, an interface part that is often overlooked while the interface enables interaction. So basically, I see every API is a formal language that we expect our programs to use to talk to each other. But ironically, at the same time, there are always people behind these machines. So, the culture of human beings meets each other. And that’s why it’s so important for their design. Today, we’ll be looking at the admin use case.  

Adyen is a global FinTech company that does payment processing and provides other financial services worldwide. We support more than 200 different payment methods. And we are operating globally. We’ve observed and still are observing a fantastic growth of our platform. We are serving many companies from completely different industries, with very different challenges and expectations. API is the bread and butter of our business. We are a single platform, and this is our conscious choice. APIs make all parts of our system interconnected, both internally and externally.

We have dozens of public APIs. Internally, we have 1000s of different services and APIs supplying these public APIs. We provide our APIs for different platforms. So for the web, mobile, terminals, and many other devices. We have hundreds of thousands of API calls per minute. At peak times, we have much more, so it’s quite an intensive platform operation. We have a private cloud distributed across different regions globally. In 2020, we processed more than 300 billion Euros. We need to be highly available 24/7. There are a lot of challenges on the platform related to the technology choice. Security is paramount. Managing all of this can be very complicated.

Complexity of API Management

Payments, never sleep. If you’re operating globally, your platform should be highly available 24/7. Another reason for this complexity is that we have existed since 2006. There are a lot of existing customers, a history of decisions, and a lot of integration that we always need to keep in mind. You need to make sure that you’re not breaking all your legacy. But you should also look at this positively because this is what made your platform so successful. This is just more responsibility to maintain and evolve properly.

Nowadays, we have designed our development organization with many autonomous teams that own their products and different parts of our business. These teams have people from different disciplines working together on different parts. But this means that they also have a lot of freedom in designing, deploying, and delivering APIs to the market, which is excellent. But it’s also a challenge. So to summarize, as you can imagine, API management and API governance in these circumstances is a real challenge.

Another interesting point that comes to mind is that ideally, you want to control everything in one place with such a big platform, such a big responsibility with a single handle controlling all your APIs. However, as we know from this example from Gartner, and our experience, in general, doing so can quickly become a bottleneck. 

You do not want to do this if you want your teams to move faster. 

So having all this in mind, the key concept that we learn throughout this way is any decision is never purely technical or non-technical. They’re always a hybrid.



Embedding API design into the company culture

It is about embedding API design processes, standards, and sharing knowledge across the company and how this can clash with the existing development culture that you have in your organization. Culture is how we do things here. So this is how we create new products, write, test, and deploy our code, what we use, and when. Many things in processes are already engraved in the organization, into people, and your colleagues. So you cannot just come up with a new process and say, “Okay, now we start designing the API, and everything should be done that way.” Of course, the challenge can be different in different organizations. 

We have some principles and key ideas that every development team follows. 

  • We prioritize the current merchant experience over future features.
  • To think like the merchant, we meet them.
  • We design for 20x
  • Expose your work early
  • We are all designers, architects, coders, testers, security officers, and operations engineers.
  • We all make mistakes, but we seek help as soon as we find out
  • You own when, where, and how your code does live
  • Your code should be understandable at 4 am under stress.
  • We embrace new technology when it has clear benefits
  • Our tech stack is open-source of built in-house.

This is not something set in stone, something that we evolve, but also something that we always keep in mind when designing our platforms. This is also related to public APIs. So, we expect teams and developers to be autonomous, which means a significant level of ownership, both in designing solutions and implementing them. Every member of the team should go the extra mile and make decisions about API design. But then the challenge is that not everybody has knowledge about API design or about public consideration that we need for public APIs.

API design decisions are complex and impactful. They require diverse knowledge from different people. So basically, when we’re designing an API, we check the business requirements and terminology. So, for business discussions, we need people representing the product side, knowledge experts in payments, banking, or other parts of the industries. At the same time, there are very specific questions related to technology. 

At the same time, the challenge here is that we cannot spend weeks designing an API as we want to be fast to the market, and this means that there is also time pressure. 

All the public APIs that we develop and put online are done when used in production by somebody. This also means that you can make a quick decision and then think. Even when you create a new, better version of your API, the previous version you designed and put in public usage is being used by somebody.  Keeping all this in mind, we have found some good solutions, which worked in our case.

Road to successful API governance

We started with a group of people who are willing to dedicate their time to API reviews and spend time on API governance efforts. Ideally, you should be looking for a diverse group of people representing different parts of your platform, your business, and your technology. This group can be responsible for three different areas of API design where you do ideation and feedback before the development. This is followed by API reviews when you evaluate the use of existing APIs and come up with improvements. The group should be responsible for maintaining the style guide and different tools that help you design the API. But, the review group should not act as API police.

The developers should be empowered and should come to you for a question or an answer or to get advice. You shouldn’t be chasing after them; you shouldn’t be controlling them. This is the only way it will work.

It is important that you all look at the same source code. So it’s important that you use some visual tool for your API design. We found that Stoplight addresses this pretty well. 

You must note all findings and documentation in a place that is easily accessible to relevant teams. It’s also important that everyone in the organization can easily contribute to that. You can put it in a Git repository, maybe on some wiki page or somewhere else. It’s important to explain what you do with your API when you design it and explain why, which is quite complicated and takes some time and effort. In addition to your style guide, you can also introduce something like architecture decision records.

Having a style guide is important, and we can have hundreds and hundreds of different rules; nobody will remember all of them. It’s also important to have some handy tools to help them avoid mistakes. Open API standard has become the de facto standard for describing and designing any web API. There are other emerging standards also depending on what technology you’re using. But open API is very helpful in this case. You must look at open API files and their API contract. You can do contract testing and see if something has changed and if it’s violating the contract and maybe needs a new version of your API.

With all these API design efforts, you can always develop a great API. There will always be some need to change something. And this means that you need to invest in a proper evaluation and versioning strategy.

It is also important not to underestimate the value of good tooling. So make the right thing to do the easiest thing to save energy, especially since the human brain is just wired to conserve whenever it’s possible. We spend far more time during what’s easy than doing what’s right. Even if you come up with a brilliant API design, you still need to understand what your development teams use to create this API. For example, if they’re using certain frameworks or certain architectural decisions, this will tell them to make the API in a certain way. You always need to look at the end-to-end API lifecycle in your organization to understand the bottleneck. You should probably be investing some time and ensuring that if somebody is using this framework, there is the right piece of documentation or sample code that helps them create an API in the right way.

To summarize three pillars of a good API design integration into your organization-

  • API design, where collaboration is the key. 
  • API development – Evaluate the entire lifecycle. Automate as much as possible and remove bottlenecks. 
  • API Consumers – Always think about your API consumers. Always be in between your organization and people who are using your API. Here, you can get feedback from different teams and input this into your guides and discussions.

APIdays | Events | News | Intelligence

Attend APIdays conferences

The Worlds leading API Conferences:

Singapore, Zurich, Helsinki, Amsterdam, San Francisco, Sydney, Barcelona, London, Paris.

Get the API Landscape

The essential 1,000+ companies

Get the API Landscape
Industry Reports

Download our free reports

The State Of Api Documentation: 2017 Edition
  • State of API Documentation
  • The State of Banking APIs
  • GraphQL: all your queries answered
  • APIE Serverless Architecture