Reference pages: an API’s inventory and checklist
Once a developer knows how to use your API, they will need detailed instructions on how to build the actual integration. Experienced developers already familiar with an API, including its creators, will have a hard time completing an integration without access to the API reference. That is why developers will often refer to them as “the API documentation”. This is a dangerous practice, as it implies that an API reference would be the only documentation an API needs, we talked about this in our previous posts.
In this post we’ll show how the developer portals in our research sample implemented their reference pages, compare their formats and labels, and try to deduct best practices you could apply on your developer portal.
Structure and subcomponents of the reference page
Developers will use the API reference during development, so it is very important to include elements that minimize the time it takes to find a specific function or parameter and to provide tools that help them browse and understand your endpoints.
There is much less variation between reference page implementations than between the documentation types: developer portals usually list the reference topics on the left, and categorize descriptions and code snippets into one or two columns on the right.
In our research sample, API reference pages optionally contained the following subcomponents:
- Code snippets / sample code to provide examples of how developers can use and test the API code
- Code language selectors so developers could switch the code samples to their preferred implementation language
- Descriptions of terms and processes that a developer needs to know to understand an API
- Search bars to speed up developers
- CTAs (Call to Action), e.g. to code snippets on GitHub, community support on StackOverflow, a registration form, or to contact the support team
- Collapsible columns to unhide/hide content: developers can get more details when they need them, but they are not shown by default so developers don’t get overloaded. This also makes it easier to scan the docs for relevant information
Reference pages in the developer portals’ information architecture
In our research we reviewed 12 overview pages of 10 companies (IBM Cloudant and Apigee both have separate docs and developer overview pages).
- 9 overview pages had a direct link to topics, descriptions and reference code.
- The “Documentation” component on DigitalOcean’s overview page linked to a subpage with a CTA to the reference docs.
- IBM Cloudant (“Browse the API reference”) and Apigee ( “Documentation”) had links to their docs overview pages (see first bullet point).
We observed 2 patterns:
- a direct link to the reference pages or
- a second overview page that lists additional documentation topics (e.g. metadata, support).
In a sample of ten, three developer portals listed the API reference together with other documentation components (like onboarding documentation, guides and tutorials) in a hierarchical menu. To get to the reference docs developers need to unfold this menu first. The other 7 developer overview pages provided a link to a subpage dedicated solely to the API reference.
Dwolla took developer engagement even further, with a sample code in the “Try it out” section on their overview page that enables developers to test and explore code without even visiting the reference documentation.
Various names for API reference pages
The terminology used to refer to API reference pages was:
- API reference (mentioned 4 times)
- API docs (2)
- (Company name) API (2)
- Documentation (2)
- API documentation (1)
- Documenting an API (1)
- Reference (1)
- API (1)
Best practices to set up a reference page
Reference pages should be user-friendly:
- Add concepts to your API reference where possible to help developers understand the reference code (we already mentioned Michael Meng’s talk at WTD Prague 2016, who did research on how developers read documentation).
- Include links to other site sections on the developer portal (eg. FAQs, guides, …) or to external community resources as GitHub and Stackoverflow.
- Make sure you include code snippets in various languages.
- Clear terminology with an easily findable link on the overview page helps your developers to find the code they need.
- Include color identifiers, arrows e.g. to indicate chapters on the reference page.
- Add descriptions of processes and definitions of domain language (industry specific terms) used in the code.
- Make the sidebar (if any) simple: provide an understandable table of content or faceted search system.
Developer Portal: Components Series In this series we give a thorough overview of the documentation components used on developer portals.
_Many thanks to my colleague Kristof Van Tomme for co-authoring and to developers Tamás Demeter-Haludka and László Csécsy for their help to interpret specific API reference terminology._
For further reading on best practices, read Kata’s post with UX tips for API documentation.
APIs are difficult to describe when you’re not a developer. Have you already read Laura’s blog post “What is an API” to help you out?
