Leading the Way As An API Champion: A Pragmatic Approach To API Style Guides

A note on the ideal vs. reality of API style guides.

Photo by Taylor Flowe on Unsplash

One of the first steps to building out an automated, scalable, distributed design review process is to start with socialising and collaborating on an API-style guide.

There are many excellent articles on the topic of style guides such as Nordic APIs, Tyk and of course Stoplight

I've initiated an API Community and my enthusiasm is so infectious that all my colleagues can't wait to join the API Style Guide party. They have zero existing workloads or OKRs and are happy to drop everything. And by the way, I've got a bottomless piggy bank for hand-picking our favourite API tools, and hey, who needs data privacy anyway, right? Just send all our data to a vendor’s cloud.

The ideal state for establishing your corporate API Style Guide would be to have a small group of dedicated individuals to get the boat in the water. Like many organizations, particularly in light of recent market conditions, we're facing the challenge of accomplishing more with fewer resources.

In reality, people are busy with existing workloads and OKRs. Many may not be aware of the role and importance of APIs or style guides.

In the meantime, persistence is key even when the benefits may not be immediately evident or measurable.

Here is how I've approached it:

Started writing stuff down.

Obvious innit?

Last year, I established a style guide on GitHub, constantly updating it with questions and answers that surfaced in Slack conversations. It's exciting to witness a modest (admittedly small, but every win counts) yet steadily increasing interest and engagement with the style guide.

Hooked the Git repo up to Slack to increase visibility

Once I had sufficient content and my membership in the Slack channel increased I hooked it up to Slack. This was starting to bring some visibility to the initiative.

Focused on breadth of content rather than correctness

There will be time for pedantry.

It’s early days and it’s as much about consciousness-raising and spreading the word that you've thought so others don't have to. Don't be inflexible.

Didn't worry about the process

Happy to say that I may now need to start thinking about some lightweight processes and improving documentation as others are making PRs against the repo and asking questions.

Be thankful and appreciative if and when others contribute

It’s challenging to find and motivate champions in the organisation, especially when many are already occupied with other commitments. Often, their time and dedication is sporadic, fitting in wherever their schedules allow.

Saying "Thank you" and acknowledging others’ contributions doesn't take much.

Final Thoughts

For some time organisational efforts have focused on our Data First operating model. We have launched our Data Academy - an initiative to improve data literacy and build a community around data and data processing topics.

I mention this as we are an organisation that recognises the power and value of internal communities.

This leaves me feeling optimistic that API initiatives will thrive and flourish in the not-so-distant future however these initiatives need time.