API spec files and versioning

[shilpa-padgaonkar]

There is currently a pull request #123 open in the commonalities WG to document the general guidelines for creating subproject releases. This also touches on the API versioning topic. From the ongoing discussions and comments, it would be helpful to know the general opinion on how we should version our API spec files, as the existing semantic versioning format isn't the most manageable one moving forward. An alternative of using alpha, beta, stable versions is suggested as a part of this poll. A good read on this versioning style can be found here, K8s API versioning.
Please note that this API spec versioning is != API-Subproject release versions

In addition to voting, feel free to add your comments to this poll.

[jlurien]

Hi @shilpa-padgaonkar. I'm trying to understand the implications on our project of what K8s does and I don't fully understand how we would apply it. Looking into k8s repo for their API specs, which can be found here, In see that they set info.version to "unversioned" internally in the API spec:

info:
  title: Kubernetes
  version: unversioned

, and the use of v1, v1alpha1, etc is limited to the version part of the paths, for example /api/v1/namespaces or /apis/networking.k8s.io/v1alpha1/clustercidrs. Are we voting to use this instead of the current vMAJOR.MINOR.PATCH scheme? It sounds to me that k8s concepts of alpha and beta are intended to reflect the status of the implementation behind the API, and not directly related to the maturity of the API specs, but I'm not that familiar to k8s APIs.

[hdamker]

Hi @jlurien. I don't know exactly why the (generated) json files of k8s do contain this "unversioned" info. But for a release the API definition files always belong exactly to a Kubernetes version. E.g. here you have the one page version generated out of API Version v1.26.0 of Kubernetes (OpenAPI v2 is a single, generated json file).

The important part: most of the API definitions within this release are stable v1 versions, but there also some API groups which are only available as v1alpha1, or as two different beta versions (flowcontrol), or even two stable versions v1 + v2 (autoscaling).

Maybe Kubernetes is not the best example, as it is a huge project, with lot of API groups and lots of providers, and it comes with the implementation code. Therefore let's have a look on a smaller project within the Kubernetes universum, the Kubernetes Gateway API, which is following the K8s versioning strategy. It is comparable to our exercise, as the project itself defines mainly the API (plus CRDs etc) while there are several provider implementations.

The first release of the project (v0.1.0) was v1alpha1, today they are at release v0.6.0 and have two API versions v1beta1 and v1alpha2, but not yet a stable version (which would be "v1"). They are very carefully with graduating resources (= API objects) from alpha to beta, and will not release a stable version as long they are not 100% sure that the functionality can be supported long-term. The resulting lifecycle picture:

Note: the API is written in Go ... the YAML file is generated and can be found within the releases, e.g. here for v0.6.0. The file contains for each API Object the "bundle version: v0.6.0" of the project, and then only the API version (e.g. v1beta1) within the path.

With this strategy, the project is able to introduce new API features within alpha (for implementators), mature features will be moved to beta and stable. The different channels can live in parallel.

How you would do all that with semantic versioning of the API files within semantic versioned releases without get confusion between the two independent version numbers?

[jlurien]

Thanks @hdamker for the details. After reading the links provided for k8s APIGW example I still have doubts about how the new proposal fits in our OAS3 schemas. I saw this yaml as part of their release, but it is not defined in OpenAPI/Swagger, not sure if they have another one in standard OAS.

Maybe if we use the OAS3 semantics it is easier to compare both proposals:

In OAS, versioning affects:

• info.version: (string)
• servers.url: (string), which may include a {basePath} common to all endpoints
• /{path}: (string), relative to individual endpoints

All fields are just strings so there is freedom to adopt any format. Currently we have adopted:

• info.version: {major}.{minor}.{patch}
• servers.url: (string), {basePath} set to api-name/v{major}
• /{path}: (string), no versioning

With the new model using alpha, beta, how would these fields look like? The concept of "resource" in k8s, would apply to each endpoint within the API or to the whole API (basePath)?

[shilpa-padgaonkar]

Here are other examples if you are keen to look at openapi specs https://github.com/istio/api/blob/master/type/v1beta1/selector.gen.json or https://github.com/istio/api/blob/master/analysis/v1alpha1/message.gen.json

[jlurien]

In these latest examples they are filling the versioning in info.version but they don't define any endpoint path, just components, so I still miss the whole picture. I guess they would reuse all the info.version as the basePath for all endpoints?

[hdamker]

@jlurien all k8s resources are accessed through the k8s api-server. Here is the explanation how the resource URIs are built: https://kubernetes.io/docs/reference/using-api/api-concepts/#resource-uris and the page is also explaining which API verbs can be used on resources. E.g. GET /apis/networking.istio.io/v1alpha3/gateways will get gateways for all namespaces.

Istio https://github.com/istio/api/blob/master/GUIDELINES.md point to Google API design guide. Especially https://cloud.google.com/apis/design/versioning is worth a read in our context here.