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.

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.