Iurii Gerzhedovich created IGNITE-27781:
-------------------------------------------
Summary: Improve OpenAPI spec versioning & publishing
Key: IGNITE-27781
URL: https://issues.apache.org/jira/browse/IGNITE-27781
Project: Ignite
Issue Type: Improvement
Components: rest ai3
Reporter: Iurii Gerzhedovich
h2. *1) Versioning model*
h3. *Platform vs API version*
* Platform version (e.g., 1.2.4) is the primary version for docs/spec
publishing.
* API version refers to API major version (e.g., v1, v2). Each major has its
own OpenAPI JSON/YAML.
Each platform release supports N API majors. For each supported API major, we
publish one spec.
h3. *When to bump API major*
Bump vN → vN+1 only for breaking changes, including:
* removing/renaming endpoints or fields
* incompatible request/response schema changes (type/shape changes)
* Making optional fields required
* tightening validation that can reject previously accepted inputs
* auth/permission changes that break existing integrations
* semantic changes that break reasonable client assumptions
Additive changes (new endpoints, new optional fields, additional response
fields, improved descriptions/examples) do not require an API major bump.
h3. *“Since platform version” requirement*
Any endpoint (and optionally fields/schemas) introduced after the initial
publication of an API major must include:
* “Since platform version X.Y.Z”
Implementation:
* Consider adding x-since: X.Y.Z extension field, and auto-process it.
* Consider adding “Since platform version X.Y.Z” to the descriptions
(potentially automatically from the extension field)
h2. *2) Publishing model*
h3. *Versioned docs are the source of truth*
OpenAPI YAMLs are published as part of the versioned platform docs for each
release.
Immutability rule:
* Under a given platform docs root (e.g., /docs/1.2.4/), published YAMLs are
immutable after release.
* Spec clarifications/corrections are published in the next platform docs
version (e.g., 1.2.5) without changing the API major, if no breaking API change
occurred.
h3. *URL layout*
For platform version <P> and API major <V>:
* Raw spec:
* /docs/<P>/api/<V>/openapi.yaml
* AND/OR /docs/<P>/api/<V>/openapi.json
Note: there is no “latest” for API versions.
h3. *Distribution artifacts*
For now, OpenAPI JSON/YAMLs are not included in downloadable platform artifacts
(TBD). The canonical distribution is via the docs site.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
