Versioning
Versioning lets readers switch between published versions of your API's reference, so someone on v1 can still read what v1 does. It needs the Growth plan or higher.
How it works
- Import a new spec
Each spec version you import can become a docs version.
- Publish it as a version
Under Versions, publish it and give it a label, such as
v2. - Set the default
The default is what readers see when they arrive without choosing.
- Readers switch
A version picker appears on your site. Each version keeps its own endpoint pages, so v1's reference stays exactly as v1 shipped.
Marking a version's status
On each spec version, set a lifecycle to tell readers where it stands.
| Lifecycle | Meaning |
|---|---|
| Stable | Safe to build on |
| Beta | Still changing |
| Deprecated | Being retired. Add a note and a sunset date |
See spec versions.
Guides aren't versioned
This is the part worth understanding before you rely on it.
Endpoint pages are generated per spec, so each version has its own. Guides are hand-written and shared: the same guide shows to a reader on v1 and a reader on v3. A quickstart with a v3-only endpoint in it is wrong for the reader on v1, and nothing flags it.
Two ways to live with that:
Navigation
Each version's endpoint navigation comes from its own spec, because the endpoints differ. Your custom navigation applies across the site, and guides stay put as readers switch. See navigation.
How this relates to other versions
Several things in Octri are called a version. They're separate.
| Thing | What it is |
|---|---|
| Spec version | Each spec you've imported |
| Docs version | A spec version published for readers to switch to. This page |
| Docs release | One publish from API Studio, in the history |
| SDK version | The package number, from info.version in your spec |
A reader on docs v1 could be running SDK v2.
Taking a version down
Unpublish a version to remove it from the picker. To keep one reachable but steer readers away, mark it Deprecated instead.
Troubleshooting
From the CLI
You can publish, label and choose the default version with octri docs versions.