API Style Guide, or don’t make users think

Hello! My name is Lesha Rutskoi and I am a product manager at Wrike. Prior to that, he worked at Adform and PandaDoc. For the past five years, I have been doing everything related to integrations and APIs.

Wrike is a SaaS collaboration and project management product. We want developers to build their solutions based on Wrike, and for this we need our API to be convenient. At the same time, we have 9 offices around the world, and 3 of them are development offices. It is quite difficult to create a consistent API using distributed teams that speak different languages. There is a growing likelihood that their decisions will begin to contradict each other. In this case, one cannot do without a uniform set of rules for all.

If you also work in a distributed manner and make your own API, then the Style Guide API can help you. I want to tell you what common problems it solves and how it makes life easier for developers. I will also share my experience in writing and implementing my own API Style Guide in the company.

Why do we need a convenient API?

Many readers probably had to solve problems using the not-so-convenient API. Yes, this is not very simple and takes more time, but usually you can still solve the problem.

Then why waste time and team effort to make the API better? The answer is quite simple: very often the decision about the use of your product is made by developers, especially when it comes to APIs and integrations. Therefore, it is important to think not only about user experience (UX), but also about DX – developer experience.

I will give an example. I once worked in a team that was responsible for all product integration. Often in the middle of the quarter, when our plans were already outlined, a marketer came and said: “Z has made a new marketplace and will release the next version of its platform. Soon they will have a cool public event where we can talk about our integration and success! It will be great if we quickly write this integration now. ” What did we do in this case? If an experienced developer in a team could make the minimum working prototype in three days, then most often in two or three weeks we managed to bring the task to perfect condition. If a few days were missing, then the API and documentation were so-so. It was pointless for us to redraw plans and undertake new integration – all the same, nothing worthwhile would have worked out by the due date. Remember that your product may be in such a situation – partners will decide whether to deal with you depending on how quickly and conveniently you can start working with your API.

But hardly anyone wants to design a bad API. Why does everyone get different? Typically, an API develops like this. When the startup starts to grow and the first clients come to it, one of the teams makes its endpoint and decides to transfer the version to the URL:

Gradually new customers and new needs appear. The guys from the second team are included in the work, who believe that it is better to use their own Media types for versioning:

After a while, the third team arrives. At one of the conferences, they learn that Stripe is versioning its API with major release dates. And they decide to do as well:

The result is an API that has three versioning methods. All methods work, but work differently.

As a developer, it would be inconvenient for me to use such an API. And the reason is not that I prefer one approach to versioning to everyone else. Just using several methods at the same time is inconvenient. You will have to write code three times that works with the API, or use three different libraries. And this means that there will be three times as many errors.

And there are dates and times. Even using the standard approach, data can be transmitted in different ways: by the time zone of your server, by GMT, by the time on the client, in Unix time. Clients will need to bring all the data to one format.

Error messages generally do everything differently. For example, like this:

Or so:

There is also my favorite error message:

Well, just a classic – the answer is 200 OK, inside which lies JSON with a description of what went wrong.

In my opinion, the most important thing in a good API is consistency. It doesn’t matter which approach to versioning you choose, the main thing is that it be the same throughout the API. An even more successful solution would be to take the popular approach that other companies are already taking. Most likely, your clients have already encountered it, and they have ready-made code or a library. No need to think again, you can use ready-made tools.

A single approach to creating an API is especially important for large companies with distributed teams. If ten people in the room create a startup, then each developer can simply knock a neighbor on the shoulder and agree or see the main problems during the code review. In a big company, it gets harder.

The Style Guide API will help you solve such problems. This is a document that describes the design principles of your API. If everyone uses the same approaches, it seems that the API was developed by one person, and not many different teams. This approach is much like the Code Style Guide, when teams agree on how they write code. A person from one team can look at the code base of another team and quickly understand what is happening there.

How to make your own API Style Guide?

Arnauld Lauret (known as API Handyman) created a cool site – Stylebook API. He put together a publicly accessible Style Guide, which various companies (Cisco, Google, Red Hat, government agencies, and many others) put in the public domain.

Guidelines are divided into topics on the site. For example, if you are interested in versioning, then on the “Versioning” tab you can find out how different companies solve this problem.

Learn from the experience of others! But completely copying someone else’s Style Guide is not a good idea. Still, he solves the problems of another company, not yours.

In your Style Guide, you should add topics that are close to your company and solve your problems. Maybe you have a lot of mobile applications, and the size of the answer is important to you. Then describe the principles associated with this aspect. Or you agreed with internal teams that it was time to saw the monolith into microservices that would communicate with each other through Message Broker. In this case, the API Style Guide needs to include the principles by which you are going to use Kafka or some other tool.

What else to include in the Style Guide API

Also, the Style Guide should include the basic values ​​and engineering approaches that the company adheres to.

What can they be?

• Write APIs in English. This is definitely worth doing if the company has large distributed teams. Even if today all your colleagues speak Russian and the internal documentation is written in Russian, this does not mean that in five years the company will not have an office in another country and remote employees. All the public and private Style Guide that I know are written in English.
• Follow the API First principle. First design the API and agree to use it with all possible consumers: neighboring teams, users, frontend-team. All parties involved can discuss how the proposed API is suitable for solving problems. And they will do it before the code is in the prod, which means that it will be possible to fix errors earlier and cheaper.
• Use REST and JSON. This can be important if you want the widest possible audience to use your API or platform. Despite the fact that GraphQL has become increasingly popular since 2017, not everyone knows about it. Most developers, most likely, have never used it, which means that they will increase the time for immersion and development. Why create complexity?

Further, the basic principles can be laid out on topics. For example, inside the principle of using REST and JSON, you can easily determine which topics should be described in the Guide:

• Prefer REST API with JSON payloads
  • HTTP requests
  • HTTP status codes
  • Json

Further on each topic, you can come up with the rules that all teams in the company should follow:

• HTTP requests
  • MUST use HTTP methods correctly
  • Custom HTTP headers SHOULD follow naming convention

I really like the approach that describes the need to follow the rules through the verbs MUST, SHOULD or MAY (borrowed from RFC 2119) Then, everyone reading the Style Guide will distinguish between mandatory rules and recommendations.

Here’s how, for example, it looks like Zalando:

Things to keep in mind when starting up the Style Guide

• Instruments. At the very beginning, you can select and describe standard tools that all teams will use. For example, project templates for programming languages ​​and frameworks that you use. Or general tools for logging, monitoring, load balancing and so on. You can choose either a ready-made API management solution or make your own. A clear description of the overall infrastructure will help development teams get more involved in working on the API.
• Performance. Sooner or later, on the night of Saturday to Sunday, someone will definitely try to upload several 15-gigabyte files to your system in one hundred streams. So rate limiting, file size restrictions, etc. – these are problems that are best solved in advance, and not during a force majeure situation.
• Security. Everyone seems to be used to using OAuth when it comes to REST. But here it’s worthwhile to decide in advance, for example, whether you intend to use scopes or not.
• Collections. Issues related to filtering, sorting and pagination are also best discussed in advance.
• Versioning It is worth considering what you consider to be a backward compatibility break. For example, can a developer add a new property to the response or not. What to promise users during the release of the new version. How to clean old methods. It’s better to think about it at the beginning, so that users of the product have clear expectations.
• Error messages. There are a lot of ways to make them, it is better to agree in advance which one you choose for your product.
• Data formats. A bottomless topic that includes the correct presentation of currencies, country names, etc. But it also applies to internal data: for example, if the product has a user object, then it’s better that the same user object is everywhere, and not fifteen different.
• Documentation. Remember that documentation is also, in a sense, a public interface. It will be much more convenient for customers if the internal documentation (OpenAPI specification, description of the business case) looks similar. So you can quickly find the necessary articles and not be distracted by unnecessary details.

How to implement the API Style Guide?

You have created your API Style Guide, and now it remains to implement it. This is also not easy. I will share my experience of implementing the API Style Guide in one of the places where I worked. The company had a complex structure: hundreds of engineers, dozens of distributed teams in four development offices, colleagues spoke different languages.

First you need to convince stakeholders. And here we are often talking about both technical leaders in various fields and business representatives. Everyone should understand what problems we want to solve and how the Style Guide can help. In my example, all stakeholders understood that a good API is an important advantage. Many customers came with such a request, and competitors did not doze off and actively expanded the scope of opportunities available through their API.

The next step is to find a team that will do this. In my case, the company already had a separate team that supported an external API. She best understood the need for change, because she was constantly confronted with difficulties in her work. The members of this team were pleased to participate in the project.

How did the team implement the Style Guide API?

• She spoke about the initiative at internal conferences and hackathons so that everyone in the company would understand what was being discussed. This helped to attract like-minded people who were very useful in the next stages.
• Prepared a draft Style Guide, which subsequently agreed with the API champions (more on them later).
• Presented the project to teams. The guys went to each development office and talked with almost all the teams, explained the meaning of the project and conducted trainings.
• Helped with the design of the API. It was difficult for many teams to do everything on the guide the first time. Help and additional explanations came in handy here, especially in unusual situations.
• Conducted a review. It was important to verify that all teams act according to the Style Guide.

It is very difficult for one team in a large company to implement such significant changes. Need support. Here API champions were connected – architects and techlides of each direction, who helped to introduce the idea into their teams and divisions.

When key changes occur, those often displeased. In this case, you need authority that can convince these people of the need for change. Tehlids are the most suitable people for this.

API champions in a separate Slack channel discussed emerging issues and suggestions. Minor changes were introduced immediately, while larger ones required a detailed discussion. In this case, the initiator wrote an official proposal: what problem needs to be solved, what methods of solution already exist, what advantages and disadvantages they have. Then we gathered for 1-2 days on offsite outside the office, discussed ideas, chose a solution and fixed it. Then we told our teams about the decision we made: why we made it and what needs to be done next.

Also, API champions helped to do reviews in their areas. The guys in their teams first turned to them, and then the final review was conducted by the team that was creating the Style Guide.

After some time, the API community began to form in the company. It included people who went through several review cycles, figured out what a good and correct design is, why it is needed and how to make it. We created a great chat in which everyone could ask a question, and members of the API community helped solve it.

You cannot implement the approach only at the engineering level. Sales, support and marketing teams should also understand what user scenarios are covered by the API, what value it carries, how it relates to the company’s strategy and how to properly convey information about it to customers.

We tried to introduce all this into the onboarding of most of the teams in the company, including non-engineering ones. This is also necessary so that everyone understands when, in what cases and to whom you can come for help.

Automation

The last important topic is the automation of routine processes. The review can serve as a prime example. In a large company with a large number of teams, most likely, you will need to do a lot of reviews. I don’t feel like wasting time on basic problems like a missing error description or an incorrect ID format.

Some tools can help with this:

• Zally Zalando checks to see if the OpenAPI specification matches your API Style Guide. Zally’s basic configuration checks for compliance with the Zalando Style Guide, but you can redefine and add your own rules.
• Dredd Apiary checks to see if the final REST API implementation matches your design, namely OpenAPI, Blueprint or RAML specifications.

This article is a transcript of my report with Platform Developers Conference by Miro. You can find video appearances right here.

I will be happy to answer your questions about implementing the API Style Guide. It will also be cool if you share a similar experience!

Special thanks to Daria Ivanova for her help in preparing this article!