[
https://issues.apache.org/jira/browse/IGNITE-27781?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Vadim Pakhnushev reassigned IGNITE-27781:
-----------------------------------------
Assignee: Vadim Pakhnushev
> 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
> Assignee: Vadim Pakhnushev
> Priority: Major
> Labels: ignite-3
>
> 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)
