I Wish API Providers Published Their Developer Portals On Github So I Could Submit Pull Requests
07 Apr 2015
I spend a lot of time looking through the developer portals of API providers. I see a lot of things, both the good and bad, while navigating these portals, and while some of the bad stuff I see are way too big for me to doing anything, there are many little things I see that I could help do something about. Sometimes it is just spelling mistakes, sometimes broken links, and other times I want to rewrite API descriptions, and add to the resources that are available for an API.
During these travels, I got to thinking...what if API providers published their developer portals to Github? Just like I do with my API Evangelist sites. Then I could fork their portal, and submit pull requests with rewrites of the description of what your API does, adding little tweaks, here and there, helping polish the portal--potentially making things easier for developers. I’m sure this thought scares the hell out of some companies, who can’t imagine, allowing outside input like this, but if you sit down and think about it for a while, it just might make sense.
When I was in Washington D.C., I created a default portal template that runs on Github. I might upgrade this, and make it available for API providers to use as a forkable template, to seed any API developer portal. Doing this makes it easy to provide a base set of building blocks that every API provider should start with, allowing them to delete the elements that they don’t want. I am also considering making a default one, that can be used as a starter developer portal for Internet of Things (IoT) platforms.
I thoroughly enjoy the pull requests that I get for spelling and grammar mistakes I made on API Evangelist, from some of my favorite grammar trolls. Running all of my websites on Github Pages has changed the way I tell stories, and interact with my audience. I’ve always encouraged API providers to use Github for an increasing number of API management tasks, but actually running your entire portal as a Github repo, would this to a new level. This approach could be used for larger, or smaller developer platforms, and I even use Github pages as a front-end for private API developer portals--ask me how.
It is just a suggestion for you API providers, and soon to be API providers. Github provides a very low cost, scalable way to launch your portal, and you never know, people like me who spend a lot of time in your developer portal, might actually help make it a better place. I wish more API providers would publish their portal as a Github repository, as well as graphic designers in the space help craft template portals, that providers can put to work. My portal definitions will always reflect best practices that I see across the API landscape, but they won’t always be the slickest looking when it comes to graphic design—just not my core competency.