CAMARA API Maturity Levels - proposal

This is a proposal how CAMARA can re-use project maturity levels of CNCF in API lifecycle management.

Each CAMARA API can have a maturity level of sandbox, incubating, or graduated that reflects the advancements of API specifications process and obligations of the subprojects in the CAMARA Release Management Proces. The “archived” status can be added for closed/not-finished specifications.

Here the issue Consider including Alpha and Beta labels to API versions #13 is also addressed. Semantic Versioning is related to software development, for API specification it can be referenced as the Best Practice. For prerelease identifiers arbitrary strings may be used, "alpha" and "beta" are just common convention.

Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.

For API specifications in early development (before reaching version 1.0.0) using these identifiers can be helpful when multiple versions are exposed to developers for testing APIs in their applications.

The proposal can be also related to Readiness Checklist step 6 update proposal #16.

Sandbox

Sandbox is the initial level for APIs starting development within CAMARA Project.

There are no specific requirements related to API Readiness checklist items for sandbox APIs.

Participation in meta-relase: no obligation

If API is included in the meta-release, it must support all the release requirements.

API Version: 0.x.y

The following objects are used in OAS:

^{version: 0.x.y}

^...

^basePath:

^{default: endpoint/v0alpha . . . /v0alpha1}

Incubating

Incubating API should be part of each CAMARA meta-release.

The following API Readiness checklist items should be supported:

No	Deliverables/Criteria	Mandatory	Incubating API support
1	API Spec	Y	Y
2	API Implementation	N	N
3	API Documentation	Y	Y
4	User Stories	Y	Y
5	API test cases and documentation	Y	Y
6	Tested by at least 2 operators	Y	N
7	Security review	Y	Y

Participation in meta-relase: mandatory

Participation in at least 1 meta-release (as sandbox API) is required to accept it into CAMARA Incubator.

API included in the meta-release must support all the release requirements.

API Version: 0.x.y

The following objects are used in OAS:

^{version: 0.x.y}

^...

^basePath:

^{default: endpoint/v0beta . . . /v0beta1}

Graduated

API is graduated when the release 1.0.0 is reached with all API Readiness checklist mandatory items supported:

No	Deliverables/Criteria	Mandatory	Incubating API support
1	API Spec	Y	Y
2	API Implementation	N	Y
3	API Documentation	Y	Y
4	User Stories	Y	Y
5	API test cases and documentation	Y	Y
6	Tested by at least 2 operators	Y	Y
7	Security review	Y	Y

Participation in meta-relase: mandatory

API included in the meta-release must support all the release requirements.

If needed the new API release should be prepared for meta-release, but without breaking changes .

New major version (e.g. 1->2) is needed when breaking changes are introduced.

API Version: v.x.y v>0

The following objects are used in OAS:

^{version: 1.x.y}

^...

^basePath:

^{default: endpoint/v1}

References

Semantic Versioning 2.0.0 https://semver.org/

Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.