How to Design REST API Guidelines for Your Team (For the First Time)

Photo by John Barkiple on Unsplash

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.

You don't have to be an expert to join

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.

Taking the lead

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.

10 steps to defining API guidelines for a company

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.

1. 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.

2. 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.

3. 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.

4. 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.

5. 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.

6. 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.

7. Disseminate widely

   After the guidelines were signed-off, we distributed the guidelines in all of the relevant Teams channels, with a small summary.

8. Create a Slack/Teams channel for support

   There previously did exist a channel within Teams for APIs, so we were able to use that.

9. 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.

10. 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. For weekly updates from me, you can sign up to my newsletter.