...
The following picture gives an overview of the API versions that an API can go through from inception to release.
The following section describe the details on naming, release assets, and the steps to produce a public-release API version as part of a meta-release.
...
- the API version in the OAS version field in the API definition file
- the API major version in the URL defined in the API definition file
- the Github branch for the API version : apiname-x.y.z, with extension as applicablethe API version GitHub tag on that branch apinameapi-vxx.y.z, with extension as applicable
- a GitHub release package, tagged "latest" or "pre-release", containing the API Sub-project repo for the branch
...
Release are handled per API, and the apiname API name is part of the branch and tags names to distinquih distinguish releases of APIs in the same API family.
...
| API version | API version (OAS file) | API version extension (OAS file) | API version in URL (OAS file) | GitHub tag (api = API name) | GitHub release package (name = GitHub tag) | GitHub release package tag |
|---|---|---|---|---|---|---|
| initial (x=0) | 0.y.z | none -alpha.m -rc.n | v0.y.z (exception) v0alpham v0rcn | apinameapi-0.y.z apinameapi-0.y.z-alpha.m apinameapi-0.y.z-rc.n | optional | optional [ pre-release ] |
| alpha | x.y.z | -alpha.m | vxalpham | apinameapi-x.y.z-alpha.m | optional | optional [ pre-release ] |
| release-candidate | x.y.z | -rc.n | vxrcn | apinameapi-x.y.z-rc.n | mandatory | pre-release |
| public-release | x.y.z | none | vx | apinameapi-x.y.z | mandatory | latest |
| work-in-progress | wip | N/A | vwip | N/A | N/A | N/A |
...
- With the exception of initial API versions, all pre-release API versions must have an API extension.
- An initial or alpha API version may have a GitHub release package, which must have the "pre-release" tag
- A release-candidate and public-release API version must have a GitHub release package
- Only the latest release packages of an API version may have the tag "latest".
Exception cases
Usually an API will go through the above described evolution API version steps.
However, there are some exceptions that may occur and are suggested to be handled as described below.
For initial API versions (x=0):
- breaking change: api-0.y.z–alpha.m or api-0.y.z-rc.n → api-0.y+1.0
- non-breaking change: api-0.y.z-rc.n → api-0.y.z+1
For API versions with x > 0:
- breaking change: api-x.y.z–alpha.m or api-x.y.z-rc.n → api-x+1.0.0-alpha.1
- non-breaking change: api-x.y.z–alpha.m → api-x.y+1.0-alpha.1 or api-x.y.z-rc.n → api-x.y+1.0-alpha.1
Special case: initial API versions (0.y.z)
...