There are many facets that go into the leading API portals and ProgrammableWeb has created a series of articles that help you understand what best practices are being used by real-world API providers. The series was kicked off with a comprehensive checklist of the criteria needed to build a world-class API developer portal. Subsequent Editors Choice articles including this one will provide a more in-depth look at how individual providers have executed on the various criteria.
Google recently announced a feature update to its Google Cloud Storage documentation; placeholder variables that can be replaced within the code samples. This new feature lets a developer replace a placeholder variable within a code sample with their own custom variable.
Figure 1 Placeholder variables allow you to use custom parameters in the code sample
This feature allows a developer to use parameters specific to their own instance thereby giving them a better understanding of how well the API will meet their needs. It takes the idea of interactive samples one step further by allowing for nearly bespoke code samples.
Another neat feature can be seen when a documentation page has multiple code samples that each have the same placeholder variable.
Figure 2 Changing the placeholder variable once, will change the variable for all instances across multiples samples on a page
As you can see in the image above, if you change the variable in one place, it will be replaced anywhere else it appears on the page, including within other code samples. Not only is this a time-saver, but it also ensures consistency for developers when they run the samples.
Google’s use of placeholder variables is a forward step that helps make its documentation more relevant and easier to understand for anyone new to its APIs. For this reason, Google has earned a ProgrammableWeb Editor’s Choice award for Developer Experience.