This is the fourth post in our developer portal components series about documentation patterns. Make sure to subscribe to our mailing list!

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.



Example of an API reference page with descriptions and code snippets in separate columns (DigitalOcean)



Example of an API reference page with descriptions and code snippets in one column (Mattermark)



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



Example of an API reference page with CTAs, search bar and code language selector (Keen IO)



Example of descriptions in the API reference (Twilio)



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).



Example of “Documentation” component linking to the docs overview page (Apigee developer overview page)



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.



Example of sample code (in “Try it out” section) on the overview page (Dwolla)



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.



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?



Other posts in this series:



About the author

Kathleen De Roo

Copywriter

As a copywriter and member of the content team, Kathleen is responsible for writing, reviewing and editing website copy and blog posts. She has an interest in Information Architecture.

She holds master's degrees in History and in Archiving / Records Management. Before joining Pronovix, she gained professional experience in teaching and office management and was a volunteer for several non-profit organizations.