How to Define REST API Guidelines for Your Team
I recently participated in creating API guidelines for the company I work for. Even though I had little experience with APIs, I was trusted to lead the work. I want to share with you how that worked out.
You don't have to be an expert to join
Less than two months after joining Muddy Boots, I received an email stating that work was kicking off on designing the company's API guidelines and asking if anyone was interested in joining that work.
Even though I was new to the company and had minimal knowledge of APIs, I expressed my interest immediately.
I had worked on integrations before and was educating myself more and more on APIs. I thought that being part of this work and learning from others within that group would help me increase my knowledge of APIs.
However, I had doubts about whether I could contribute anything instead of just sitting there and taking space.
I started researching APIs as much as possible in my free time to calm those doubts. I read articles and created a new API from scratch to get some hands-on experience.
So, at least, I would be able to understand what was being discussed and occasionally add some comments or ideas.
Taking the lead
The initial working group included around nine people, mostly architects or team/tech leads or representatives, and me.
In the first few meetings, we worked on the scope, expected outcome, and some basic definitions. We also started going through the first couple of sections of the Microsoft API Guidelines since we were going to use that as our base.
I was pleased that I was able to contribute and bring some thoughts to those initial meetings, mainly based on some things that I had recently read.
After a few meetings, one of the architects who led the work approached me and asked if I wanted to take the lead.
It was a big surprise to me.
I initially had doubts about whether I should be taking part in this work at all, but now I was being asked to lead it—hello, imposter syndrome!
Who am I to lead a group in creating API guidelines for the company?
The architect currently had a lot on his plate, and based on my contributions in the first meetings, he was confident that I would be able to step up.
I was delighted to be trusted with this assignment and took the challenge. Thankfully, I knew I had good people around me who could help me.
10 steps to defining API guidelines for a company
Now that I was in charge of defining the API guidelines, I needed to figure out how to do so.
So, on to Google/Bing/DuckDuckGo: "How to design API guidelines for a company."
And what do you know, "Defining API guidelines for a company: What works?", popped up, thankfully.
So, I decided I could use this guide as my cornerstone for defining the API guidelines.
Stepping through each step of the guide, here's how we did it.
Start with one API style and add more
In our case, it made the most sense to start creating REST-ish (without hyperlinks) API guidelines.
Gather a small working group
After I took the lead, I brought this idea to the working group that we would minimize the group to create the first draft and then get that draft to the broader group for a review.
The group accepted that idea, and we ended up with a small core team of three.Stand on the shoulders of giants
As mentioned, we used the Microsoft API Guidelines as our base. We had meetings every week, during which we went through the section(s) and modified them for our purpose.
In addition, we had a small backlog in which we would note down ideas, thoughts, or concepts that we would need to discuss later.
Once we finished reviewing the Microsoft guidelines, we reviewed the backlog and added/modified sections based on our discussions.Take an open-source approach
Confluence stores the guidelines because it is our collaboration tool. Anyone interested could have a look and review them.
Review and debate with a broad audience
Once we finished our initial draft, we brought it to the broader group, which included architects and team leads or representatives, to review and discuss the draft.
A few things needed ironing out, but overall, it was well-received.Get formal sign-off
Once the wider group was happy and signed it off, we brought it to an even wider group that included, for example, the head of production and head of technology, and more senior developers to get a formal sign-off.
Disseminate widely
After the guidelines were signed off, we distributed them in all of the relevant Teams channels with a brief summary.
Create a Slack/Teams channel for support
A channel for APIs previously existed within Teams, so we could use that.
Make the guidelines available in PDF format
We didn't create a PDF of the guidelines since they live in Confluence and are easily accessible, and you can see the history of changes.
However, we did restructure the guidelines a bit better, making them easier to consume and find relevant sections.Train and socialize
This is a work in progress. We have yet to figure out how to do this, but it might be a small workshop or something.
We still need to increase awareness and drive its adoption. Hopefully, automated tools and processes can help with that.
I'm delighted with how well this went and that we were able to deliver.
I'm grateful for the opportunity to participate in and lead this work. I had great people around me who could help me, and I didn't feel uncomfortable when I thought my questions were stupid.
Thanks to all who contributed to this work.
Thank you for reading.