ProgrammableWeb attempts to have as much information as possible about every API. But at some point a developer needs to visit the provider website. That’s when the portal takes over. W’ve written a lot about what goes in a portal, including the Three Cs, but what about where the portal itself goes? We dug into the ProgrammableWeb data to find common practices based on developer portal URLs.
Though not the most common, it is still considered a best practice for API providers to put their developer portals on a sub-domain. Using a sub-domain allows for a completely separate site and makes it easy to host the portal at an API management company (ProgrammableWeb parent company MuleSoft is one such provider of this service). Still, once you’ve chosen to use a sub-domain, you come to the sticking point of every garage band and community softball team: what do you name it?
Luckily, thousands have gone before you, so you can learn from eight years of ProgrammableWeb data. Here are the most common sub-domains for API portals:
The singular developer beats out the plural version and both beat out the abbreviated dev. Using api is obviously popular, though that can sometimes conflict with your actual API endpoint URL.
Slapping API documentation into your help/support sites may be convenient, but developers may think you see the API as just another feature. Similarly, though it’s been done many times, API docs within a blog post could make developers assume your have no commitment to supporting the service. And they’re probably right.
More common than a sub-domain is to put a developer portal in its own directory. Often the directory is one level below the root of the site, but serves as a separate section of the greater company or product website.
In the following list of common directories, you’ll see some similarities to the sub-domain list and some notable differences:
While api is a distant second in the sub-domain list, here is is far and away the most common directory to place an API portal. Interestingly, for directories the plural developers is preferred to the singular (the opposite is true of sub-domains).
Lastly, some API providers may choose to host their developer portal and documentation on a completely different site. Sometimes the site is specific to APIs, but other times it’s a general wiki or developer tool.
In particular, three external sites bubble up to the top when looking at the ProgrammableWeb data:
Anyone following developer issues cannot ignore GitHub, the social code-sharing community. Naturally, the developers behind many APIs choose to host information about using an API on GitHub, which makes a wiki and content management system available to its users. Plus, when already perusing GitHub, developers are a few clicks away from client libraries and other open source code from API providers.
Mashape provides not only a developer portal, but lets providers run developer queries through the Mashape servers to get management features.
PBWorks (formerly PBWiki) is a wiki in the cloud that some API providers use to share the details of their APIs.
There are clearly different ways to approach your developer portal’s URL. Some may make more sense than others depending on your situation. A simple directory is the most popular solution, while a sub-domain gives you maximum flexibility. Using an external site may provide content or technical tools that you don’t have yourself.
At the very least, now you know what URLs to check the next time you’re looking for an un-launched API. Of course, all those stealth API providers also know which URLs to avoid.
Diagram by Caninest (modified)