# API Documentation Structure and Navigation — Routebase > Trees against flat lists, how readers actually find a page, what a version switcher has to do, and branding that supports the content instead of competing with it. Canonical page: https://routebase.dev/guides/api-documentation/api-documentation-structure-and-navigation/ Chapter 9 of 10 · API Documentation · Last reviewed 2026-09-13 · The Routebase Team Readers reach a documentation page in one of three ways. They search, they follow a link from an error message or a colleague, or they work through a guide in order. A structure that only serves one of those makes the other two harder than they need to be. ## Two halves that behave differently The written guides and the generated reference want different navigation, which is the first structural decision. Guides have a reading order. Somebody new to your API should be able to start at the top and work down, so the order carries meaning and the page count stays small enough to see. The reference has no order. Nobody reads it front to back, and every entry is a destination arrived at from outside. What it needs is precise addresses and reliable search rather than a sequence. Putting both under one undifferentiated tree gives you a guide section buried under a hundred endpoints, or an endpoint list that pretends to be a curriculum. ## How to split the reference Once the reference is its own half, one decision remains, which is how much goes on a page. **One page per endpoint** gives every operation an address. That is what makes a support answer linkable and what makes a search result land on the exact thing. It is the right default for anything beyond a handful of operations. **One page per group** puts a whole resource on one page, which suits a small API where seeing everything about orders at once is genuinely helpful. **One page for everything** is convenient early because the browser's own search works across the whole contract. It stops being convenient at about the point the page takes a second to render. ## Navigation, search and the page itself Three mechanisms carry a reader, and they cover different failures. Navigation serves the reader who is browsing and wants to know what exists. Search serves the reader who knows what they want and uses their own words for it, which is why [failed searches](/guides/api-documentation/measuring-api-documentation/) are worth reading. A table of contents on the page serves the reader who has arrived at the right page and now has to find one paragraph in it, which matters most for long reference pages. Breadcrumbs are the quiet fourth one. A reader who arrived from a search result has no idea where they are. One line of context above the title fixes that. ## Version switching is part of navigation As soon as more than one version of your API is in use, the reader's first question is which one they are looking at. The switcher has to be visible rather than tucked away, the current version has to be obvious without opening it, and older versions have to remain reachable at stable addresses. Links to a documentation page live in tickets and internal wikis for years, and a version switch that breaks them trades one problem for a worse one. ## Branding that stays out of the way A documentation portal should look like yours, and the return on that stops quickly. Your logo, your colours and your typeface do the work of telling a reader whose API this is. Beyond that, decoration competes with content that the reader is already concentrating on. Two things are worth more than any visual flourish, meaning a dark mode that is genuinely readable and code blocks with contrast high enough to read at a glance. If a reader has to think about the interface, the interface has taken attention away from the API. ## In Routebase Portal appearance is edited in a theme editor with a live preview. The layout and colour decisions are then made against the rendered portal rather than against a form. _Screenshot: The theme editor renders the portal while you configure it, so navigation, typography and colour are judged on the page a reader will see._ Structurally, written pages and folders sit in one content tree. A root-level folder can be promoted to a section, which becomes a top-level tab in the published portal. That is how the guides and the reference end up as separate areas rather than as one long list. Each embedded specification can be rendered per endpoint, per folder or on a single page, and the reference can follow the specification's own folders or a flat list. Search, the table of contents and the version switcher are portal features you switch on per portal. The switcher carries a limit for how many versions stay browsable. The [Branding guide](https://docs.routebase.dev/doc-branding/) covers themes and layout, and the [Documentation Overview](https://docs.routebase.dev/doc-overview/) covers the tree and sections. ## Frequently asked questions ### How should API documentation be structured? Separate the written guides from the generated reference at the top level, because they are browsed in completely different ways. Readers move through guides in a rough order and jump straight into the reference from a search or a link, so mixing the two produces a navigation tree where neither behaviour works well. ### Should the API reference be one page per endpoint or one page per group? One page per endpoint suits large APIs, since each endpoint gets its own address that a search result and a support answer can link to. One page per tag suits small APIs, where a reader can see a whole resource at once. A single page for everything is easy to search in the browser and becomes unusable once the contract grows. ### Does documentation need a version switcher? It does as soon as consumers are still on an older contract, which is almost immediately for a public API. Without one, the page a reader arrives at describes the API you are shipping rather than the API they are calling, and the mismatch is invisible to them. ### How much branding belongs on a documentation portal? Enough that a reader recognises whose API they are reading, which is your logo, your colours and your typeface. Beyond that, branding competes with the content, and a documentation page is read by somebody who is already trying to concentrate on something difficult. --- [Routebase](https://routebase.dev/) — [Sign up](https://app.routebase.dev/): Every account starts with a 14-day Pro trial — no credit card required.