Basic API Design Guidelines Are Your First Step Towards API Governance

December 20, 2017 Kin Lane

I am working with a group that has begun defining their API governance strategy. We’ve discussed a full spectrum of API lifecycle capabilities that need to be integrated into their development practices, and CI/CD workflow, as well as eventually their API governance documentation. However, they are just getting going with the concept of API governance, and I want to make sure they don’t get ahead of themselves and start piling in too much into their API governance documentation, before they can get buy in, and participation from other groups.

We are approaching the first draft of an API governance document for the organization, and while it has lofty aspirations, the first draft is really nothing more than some basic API design guidelines. It is basically a two-page document that explains why REST is good, provides guidance on naming paths, using your verbs, and a handful of other API design practices. While I have a much longer list of items I want to see added to the document, I feel it is much more important to get the basic first draft up, circulated amongst groups, and establishing feedback loops, than making sure the API governance document is comprehensive. Without buy-in from all groups, any API governance strategy will be ignored, and ultimately suffocated by teams who feel like they don’t have any ownership in the process.

I am lobbying that the API governance strategy be versioned and evolved much like any other artifact, code, or documentation applied across API operations. This is v1 of the API governance, and before we can iterate towards v2, we need to get feedback, accept issues, comments, and allow for pull requests on the strategy before it moves forward. It is critical that ALL teams feel like they have been part of the conversation from day one, otherwise it can be weakened as a strategy, and any team looking to implement, coach, advise, report on, and enforce will be hobbled. API governance advocates always wish for things to move forward at a faster speed, but the reality within large organizations will require more consensus, or at least involvement, which will move forward at a variety of speeds depending on the size of the organization.

This process has been a reminder for me, and hopefully for my readers who are looking to get started on their API governance strategy. Always start small. Get your first draft up. Start with the basics of how you define and design your APIs, and then begin to flesh out the finer details of design, deployment, management, testing, and the other stops along your lifecycle. Just get your basic version documentation and guidance published. Maybe even consider calling it something other than governance from day one. Come up with a much more friendly name, that might not turn your various teams off, and then once it matures you can call it what it is, after everyone is participating, and has buy-in regarding the overall API governance strategy for your platform.


About the Author

Kin Lane

My name is Kin Lane and I am a technology professional with an obsession for Application Programming Interfaces, also know as APIs. You will find me half the year, traveling the world evangelizing the importance of API literacy, and the other half of the time, working virtually to better understand the world of APIs, and publish my ongoing research, and stories on my network

Follow on Twitter More Content by Kin Lane
Previous Article
API Discovery Will Be About Finding Companies Who Do What You Need And API Is Assumed
API Discovery Will Be About Finding Companies Who Do What You Need And API Is Assumed

While I’m still investing in defining the API discovery space, and I’m seeing some improvements from other...

Next Article
I Am Now Realizing That Is Not Just For API Providers
I Am Now Realizing That Is Not Just For API Providers

When I first started diving into what does, and thinking of their role in the wider API land...