10:15-10:45 / Andrew Johnston: The Trials and Tribulations of the API Style Guide

This talk chronicles one technical writer’s holmesian journey to develop an API style guide to bring order to the chaos of Shopify’s REST API. Along the way many challenges were faced and solutions were provided by studying clues and following leads! Some of these challenges include the following:

  • API Resource naming for REST APIs is hard (everybody has an opinion !)
  • API Resource naming impacts the navigational sidebar but also has implications on how you write about APIs that makes sidebar naming considerations even more complex
  • In your navigation, it’s really hard to find patterns to enforce sub-resourcing in a uniform and consistent manner
  • If you support multiple API technologies (REST and GraphQL) you should be mindful that maybe one size does not fit all

In this talk you can expect to learn the following:

  • Solutions to resource naming challenges that we adopted at Shopify
  • Best practices for documenting properties, parameters, IDs and other API-specific terminology
  • Whether or not to start property descriptions with an article (“The”, “An” etc.)
  • The best way to document booleans -The best way to indicate valid values

Also, this talk ends with a complete, end-to-end playbook for how to write your own in-house API documentation style guide! By sifting through the clues and reviewing best practices by companies such as MailChimp, Etsy, Magento, Google and others we were able to come up with our own in-house style guide solutions that solved the case.