Reference
Versions and stability
The version numbers of O3O Office Online, the API v1 stability commitment, which changes are compatible and how stable each part is.
On this page
O3O Office Online uses several kinds of version numbers for things that change at different paces. What integrators depend on is the API contract version; the service version only tells which release is running.
Kinds of version numbers#
| Kind | Current | Where to read it | Changes when |
|---|---|---|---|
| API contract | v1 | The /v1/ prefix; the api field of /o3o/status and /v1/status | Only for breaking changes. |
| Service version | 1.0.0 | The version field of /o3o/status and /v1/status | Every release, as MAJOR.MINOR.PATCH. |
| Document engine | per image | core in /v1/status; upstream.coolwsd_version in /o3o/status | When the image changes. |
| o3oscript | 1 | The o3oscript field at the script root | Only when the script schema breaks. |
| License token format | v = 1 or 2 | The v field of the payload | When the token format changes. |
The versions.json manifest | Repository root | Every release; it feeds the Compatibility matrix. |
# Gate, DocBuilder and document engine versions
curl -s http://localhost:8080/o3o/status | jq '{service, version, api, upstream}'
curl -s http://localhost:8080/v1/status | jq '{service, version, api, core}'API v1 stability commitment#
Throughout v1, O3O only changes the API in backward-compatible ways. Every breaking change waits for a new API version.
| Compatible change (still v1) | Breaking change (needs v2) |
|---|---|
| Adding an endpoint | Removing or renaming an endpoint |
| Adding an OPTIONAL request field | Adding a REQUIRED request field |
| Adding a field to a response, callback or event | Removing, renaming or retyping a field |
| Adding an error code, a callback event type or an enum value | Changing the HTTP status or code of an existing case |
Rewording a message | Changing the unified error format |
| Adding a format to the conversion matrix | Changing a signing algorithm (HS256, HMAC SHA-256, Ed25519) or how signatures are computed |
Writing integrations that stay compatible#
- Ignore unknown fields in responses, callbacks and tokens.
- Handle unknown error
codevalues by HTTP status class. - Answer 2xx to unknown callback event types instead of failing.
- Do not parse
message; do not rely on JSON key order. - Check that the
apifield equalsv1when your application starts.
When API v2 arrives#
API v2 will open under a new prefix and run side by side with v1 for a period. The v1 support period and end date will be announced together with v2 on the Changelog page.
Stability of each part#
| Part | Level |
|---|---|
DocBuilder /v1/* (11 endpoints), error format, rate limit headers | Stable |
/o3o/status, /o3o/limits, /o3o/healthz | Stable |
O3O.Editor: config, 7 events, 5 methods | Stable |
| Document and job callbacks, signing scheme | Stable |
| License token format, o3oscript v1 | Stable |
/o3o/demo* | DEV machines only; may change at any time |
/o3o/auth, /o3o/wopi/* | Internal, not a public API |
/browser, /cool, /hosting, /lool | Editing server paths. Use them through O3O.Editor or the WOPI protocol; internal details may change with the image. |
| Limit and price figures | From plans.json; may change with pricing policy and is not an API change |
Status labels on documentation pages#
| Label | Meaning |
|---|---|
| Stable | Shipped in v1 and covered by the commitment above. |
| Beta | Works, but the deployment or documentation may still change, for example the Docker bundle running the DEV image. |
| Coming soon | Not implemented in v1. Do not plan on it until it becomes stable. |