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.
0 comments