I recently took part in creating API guidelines for the company I work for. Even though I had little experience in working with APIs, I was trusted to lead the work. I want to share with you how that worked out.
Less than two months after joining Muddy Boots, I got an email saying there was a piece of work kicking off around designing the company's API guidelines, and if anyone was interested in joining that work.
Even though I was new to the company, and with minimal knowledge on 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 my doubts about whether I would be able to contribute anything instead of just sitting there and taking space.
To calm those doubts, I started researching APIs as much as I could in my free time. Both by reading articles and creating a new API from scratch to get some hands-on experience.
So at least I would be able to understand what was being talked about and occasionally be able to add in some comments or ideas.
The initial working group included around nine people, mostly either 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 sections of the Microsoft API Guidelines, since we were going to be using that as our base.
I was pleased that I was able to contribute and bring in some thoughts in those initial meeting, mainly just based on some things that I had recently read.
Then after a few meetings, I was approached by one of the architects, who lead the work, and asked if I wanted to take the lead of it.
It was a big surprise to me.
I initially had doubts about whether I should be taking part in this work at all initial, but now I was being asked to lead the work - Hello, imposter syndrome!
Who am I to lead a group of creating API guidelines for the company?
The architect currently had a lot on his plate, and based on the contributing I had made in the first meetings; he was confident that I would be able to step up.
I was delighted with being trusted with this assignment and took the challenge. Thankfully I knew I had good people around me that would be able to help me.
Now that I was in the lead of defining the API guidelines, I needed to figure out how to do just that.
So, of 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 on how to define 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 a 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 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, where we would go through the section(s) and
modify for our purpose.
Along with that, we had a small backlog where we would note down
ideas, thoughts or concepts that we would need to discuss later on.
Once we finished going through the Microsoft guidelines, we went
through the backlog and added/modified sections based on our
discussions.
Take an open-source approach
Confluence stored the guidelines because that's our collaboration tool. So anyone could have a look and review if interested.
Review and debate with a broad audience
Once we finished our initial draft, we brought it to the broader
group, that included architects and team leads or representatives, to
review and discuss the draft.
There were a few things that needed a bit of ironing out, but all in
all, 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 the guidelines in all of the relevant Teams channels, with a small summary.
Create a Slack/Teams channel for support
There previously did exist a channel within Teams for APIs, so we were able to use that.
Make the guidelines available in PDF format
We didn't create a PDF of the guidelines since our guidelines live in
Confluence and are easily accessible, and you're able to see the
history of changes.
But we did restructure the guidelines a bit better, so it would be
easier to consume and find relevant sections.
Train and socialize
Work in progress. We have yet to work out how to do this, but it might be a small workshop or something.
We still need to increase awareness and drive adoption of it. 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 take part in and lead this work. I had
great people around me who were able to 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.