It’s normal, especially in large companies, for different product/service groups to follow their own guidelines and best practices for API design. When companies grow through a merger or acquisition, even more variety gets added to the mix. The problem with having different API guidelines for each team includes, but is not limited to:
- The more difficult it is for API consumers like developers to work with APIs, the less likely they will stick to guidelines.
- It’s harder to build common/re-usable tools and processes, which leads to repetitive efforts across teams and wastes valuable engineering time.
- An increase in the time to market for solutions built on top of APIs because of a variety of APIs increases the time to integrate into solutions.
While the need to have common API guidelines across a company is clear, the process of defining them can be a bumpy if not approached sensibly and with sensitivity. Here’s what worked for us:
- Start with one API style and add more — There’s no need for mandating one API style over others (REST/GraphQL/Event Driven/gRPC). There will always be legitimate use cases where one style fits best. Start by defining API guidelines for the most commonly used/needed API styles, then add more when existing types don’t fit your needs. In our case, we started with REST guidelines.
- Gather a small working group — Form a small core team of two or three people who draft the guidelines. Smaller groups are effective and faster. It is always easier to have a proposal reviewed by a large group than to have two dozen people come up with a draft proposal.
- Stand on the shoulders of giants — There are enough published guidelines out there, and it makes sense to build on top of one or two of those instead of creating your own from scratch. We based our work (and gave credit where it was due) on the REST API guidelines published by Microsoft, Adidas, EMC, Apigee, and JSON API. We only changed what didn’t fit for us.
- Take an open source approach — Treat the guidelines as open source code. Having a repo on GitHub/Bitbucket makes it easier to collaborate, contribute, and review. You can see an image of a BitBucket repo with the Citrix API guidelines below.
- Review and debate with a broad audience — Once the your draft is ready, it needs to go through and review, discussion, and debate with a broader audience. In our case an API virtual team was created, which included members from all major product and service groups in the company. It helps to have recurring meetings with a specific agenda for each meeting. The participants should review the agenda sections and come with their feedback and comments. These sessions are usually very intense and entail passionate debates, which is good. It is important to record the meetings for review and take detailed notes/action items for follow-up. The follow-up items can be discussed on Slack and resolved before the next meeting. The changes made based on feedback are circulated in Slack as pull requests, which can be further discussed and eventually agreed upon and merged. The whole process will take multiple weeks depending on the number of sections in the guidelines, but it is critical because it’s where real collaboration and polishing happens.
- Get formal sign-off — After due diligence on the guidelines, it is important to get a formal sign-off from all the collaborators to make sure that everyone had a chance to read it, get questions answered, provide feedback, and show their willingness to adopt it for all the future API design. It’s interesting how some people take things seriously only when they are asked to officially sign off. And it’s always better to get the sign-off/objections earlier than later.
- Disseminate widely — Once you’ve gotten a formal sign-off on your guidelines, you should widely disseminate it in the company. Recruit a senior executive to share the announcement to all of engineering for greater impact.
- Create a Slack channel for support — As more people go through the guidelines, they may have questions. It helps to have a dedicated Slack channel to discuss those questions. In our case, the slack for the API virtual team is open to everyone, which means all the discussions during the draft and review stages are available to everyone who is interested. Having all API virtual team members on the same channels helps scale the responsiveness of the channel.
- Make the guidelines available in PDF format — While Git/Bitbucket repos are a great way to collaborate on the guidelines, once it is approved, it’s helpful to have a reader-friendly format of the guidelines for easy consumption. In our case we created a Jenkins job to publish a PDF version of the guidelines whenever a PR was merged to master.
- Train and socialize — Creating offline and classroom-based training material for the guidelines is a good way to increase awareness and adoption.
Defining and publishing the API guidelines for the company is a major first step. The next steps include driving adoption through processes and tools. In our next blog we will look at how we can ease the life of API Developers through automated tools. And check out the first blog in our series.
