Real-world Patterns 2: Reference Docs

Key points in this video

Reference docs usually follow a certain structure

  • An Overview section that lays out basic info about the API
  • Sections about authentication, rate limiting, errors and any other info specific to the API
  • List of endpoints, with some logical grouping
  • Each endpoint should have basic technical info (URL, parameters, response structure), but can also include helpful commentary or contextual info.
  • Tip: Make sure to include a description of what the endpoint does. The endpoint’s URL might make that obvious to you, but your users might not get it as easily.

Reference docs can be single-page or multi-page

  • Single-page sites means less waiting for pages to load. The maintainer can also avoid implementing a custom search functionality if they don't have th resources, since browser find (Ctrl-F/Cmd-F) is available.
  • Multi-page references are useful if you have a lot of endpoints and you go into detail on them.
  • Large APIs can be single-page at group level
  • Tip: On a single-page site, make sure to use anchors and a persistent sidebar so users can get around easier.
  • Tip: On a multi-page site, avoid splitting items too much to avoid fragmentation
  • Tip: A good sidebar or table of contents provides users with the “big picture”, single or multi-page.

Complete and Continue