Versions Compared

Old Version 63

changes.mady.by.user Tanja de Groot

Saved on

compared with

New Version 64

changes.mady.by.user Tanja de Groot

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Info
titleAPI VERSIONING IN A NUTSHELL

API versioning is done using SemVer 2.0.0: vx.y.z with x, y and z being numbers indicating MAJOR, MINOR and PATCH versions.

In addition to the target public -release API versions x.y.z, internal internally to the CAMARA project during the API release cycle, process version extensions are used for pre-releases (described in the section below):

  • alpha API versions

  • release-candidate API versions

Finally,

  • work-in-progress (wip) is used as the API version before the first pre-release and between 2 pre-releases

  • as an exception, initial API versions (APIs with MAJOR version x = 0) may have both the MAJOR and the MINOR version number (v0.y), separated by a dot ("."), in the API version in the URL, e.g. {apiRoot}/qod/v0.10

The following types of API versions are used throughout an API's release cycleprocess:

  • work-in-progress (wip) API versions used before the first pre-release or between pre-releases. Having "wip" in the API version field indicates that PRs are ongoing and that the API is not usable by API consumers. The first PR should set the API version to wip, and the next "release PR" shall set the API version to the next (semver) x.y.z version.
  • alpha (x.y.z-alpha.m) API versions (with extensions) for CAMARA internal API rapid development purposes
  • release-candidate (x.y.z-rc.n) API versions (with extensions) for CAMARA internal API release bug API bug fixing purposes
  • public-release (x.y.z) API versions for publication as part of a meta-release. These usage in commercial contexts. Public API versions only have API version number x.y.z (semver 2.0), no extension. The public -release API can have one of two maturity states: 
    • initial - indicating that the API is still not fully stable (x=0)
    • stable - indicating that the API has reached a certain level of maturity (x>0)

The use of the different API versions throughout the API release cycle process is illustrated in the following figure.

Image RemovedImage Added

The next sections provide the definition of terms used and the description of the different API version types when moving through the release cyclerelease process.

Table of Contents

Definitions

...

    url: {apiRoot}/qod/v2

  • Once a stable public-release API public API version is created, the API version in the URL shall ONLY contain "vx", and never include an extension.
  • Exception: For initial public -release API versions 0.y.z, the MINOR number may be included in the URL, e.g. v0.y. A dot (".") is used for readability.
    • in this stage of the API development, y is used to indicate MAJOR (breaking) changes, and z is used to indicate MINOR (non-breaking) changes. Patches, if needed would also increase z. 
  • For alpha and release-candidate API versions, the API version extension shall be included in the URL, but without any hyphens or dots.
    • Example: in the URL of an alpha API version 2.y.z-alpha.1, the version in the URL is v2alpha1.

...

The following tables provides the characteristics of the different API version types that an API will go through during its release cycleprocess.

API version typePurpose & characteristics

work-in-progress (wip)

The purpose of a work-in-progress API version is to indicate that the API is unstable due to one or more PRs being committed, possibly resulting in temporary inconsistencies.

  • A work in progress (wip) API version has the following information in the API OAS definition file: 
    • Info object - version: wip (instead of x.y.z) 
    • Servers object - url: vwip (instead of vx)
  • A wip API version may exist in 2 cases
    • during the first introduction of a new API upto the creation of the first alpha API version
    • during the time that one or more Pull Requests (PRs) are committed after a given release of an API.
  • Between different PR commits, the API version remains "wip".
  • After or with the last PR commit, the API version and URL version are set to the next API version.
  • The maintainers of the API decide on the release (or not) of the resulting next API version, implying that its corresponding release assets will be created.

alpha (alpha)

The purpose of an alpha API version is to support rapid development of an API and the creation of test implementations for feedback purposes.

  • An alpha API version (x.y.z alpha.m) is an intermediate API version with changes with respect to a previous API version.
  • An alpha API version cannot be part of a CAMARA meta-release. It needs to go through the below release-candidate API version(s) API first.

release-release-candidate (rc)

The purpose of a release-candidate API version is to allow for (only) bug fixing encountered during further API implementation testing. 

  • A release-candidate API version (x.y.z-rc.n) is a pre-release of an API version which is stabilized and intended to become the next public-release API public API version.
  • It shall be used to create API implementations and test the API and to create required release assets.
  • A release-candidate API version can be proposed for meta-release. In this case, the public-release API version needs to be prepared.

public-release

The purpose of a public -release API version is that it can be used by organizations outside CAMARA in application development and commercial contexts.

  • A public -release API version (x.y.z) can be more or less mature:
    • A public -release API version with x=0 is referred as an initial API version.
    • A public -release API version with x>0 is referred to as a stable API version.

initial

public-release

Initial public -release API versions only exist for new APIs.

  • They are API versions with x = 0 (0.y.z without version extension).
  • Exception: for an initial public -release API version, the API version in the URL may also include the y (MINOR) version number v0.y (with the dot). This is to simplify the testing of different initial public -release API versions.

    For initial public -release API versions:  

    • An update due to a breaking change in a public -release API version 0.y.z results in a next public API version: 0.y+1.0. Example: 0.9.0 → 0.10.0

    • An update due to a non-breaking change results in an API version change from 0.y.z to API version 0.y.z+1. Example: 0.9.0 → 0.9.1

stable

public-release

Stable public -release API versions are public API versions with x > 0 (x.y.z without version extension).

Stable public -release API versions are the ones recommended for use in commercial applications. The user can expect that subsequent API versions will be backward-compatible with the one they are using, unless explicitly announced otherwise.

Creation of a public

...

API version

To create a public -release version of an API the following steps need to be taken:

  • First, using wip in the API version, develop your API until it is sufficiently stable to create a first alpha API version 0.1.0-alpha.1
  • Create one (or more) alpha API versions to stabilize the API
  • Create the first release-candidate API version for the M3 milestone (stable proposed API version for testing)
  • Create one (or more) release-candidate API versions between the M3 and the M4 milestone following feedback from testers
  • Create the final release-candidate API version for the M4 milestone (stable version proposed API version for public -release)release)
  • Finally, create the public API version Finally, create the public-release API version for public-release and, possibly, for inclusion in the meta-release
Info
titleIMPORTANT
All alpha and release-candidate API versions are INTERNAL to the CAMARA project and meant to be used only for the API development and release management process. Usage for other purpose is at the user's own risk.

The below table gives an overview of the API versioning through the release cycleprocess. The column headers mean the following:

  • API version type: refers to the stage in the API release cycleprocess: wip, alpha, release-candidate or public-release.
  • API version: (without or with an extension) is what is put in the version field in the API OAS definition file.
    • NOTE: a public-release API public API version shall never have an extension.
  • API version in URL (initial/stable): is a lowercase "v" followed by the MAJOR number from the API version. This is put in the URL field in the Servers object in the API OAS definition file.
    • NOTE: for an initial API version (x=0), the API version in the URL is exceptionally allowed to contain both the MAJOR and the MINOR version numbers (v0.y).
  • API version can be released: A release can be created for the API version (with or without (for alpha) a release package).

...

API version types in the release processAPI version
(OAS Info object)		initial (x=0) API version in URL (OAS Servers object)
stable (x>0) API version in URL (OAS Servers object)API version can be released
work-in-progresswipvwipvwipNo
alphax.y.z-alpha.mv0.yalphamvxalphamYes (internal)
release-candidate x.y.z-rc.nv0.yrcnvxrcnYes (internal)

public-release

x.y.z

v0.y

vx

Yes

Precedence examples for API versions throughout its the release cycleprocess:

  • 0.1.0 < 0.2.0-alpha.1 < 0.2.0-alpha.2 < 0.2.0-rc.1 < 0.2.0-rc.2 < 0.2.0 (initial public -releaseversion)
  • 1.0.0 < 1.1.0-alpha.1 < 1.1.0-alpha.2 < 1.1.0-rc.1 < 1.1.0-rc.2 < 1.1.0 (stable public -releaseversion)

Update of a public

...

API version

Updates to a public -release API version can concern MAJOR, MINOR or PATCH changes to the API definition.

  • For MAJOR or MINOR changes, the process is the same as for the creation of a public - API version (see previous section), going through alpha and release-candidate API versions to create the update updated public API version.
  • For PATCH changes, the API Sub Project can decide to either
    • apply the CAMARA API release process, as for MAJOR and MINOR changes resulting in a new API version x.y.z+1
      • 1.0.0 → 1.0.1-alpha.1 → ... → 1.0.1-alpha.m → 1.0.1-rc.1 → ... → 1.0.1-rc.n → 1.0.1 (next stable public -releaseversion)
    • apply a short cycle to process to create a maintenance-release of the public API version.

It is recommended to have maximally 2 consecutive public -release API versions available at any given point in time.

...

  • never change an endpoint name; instead, add a new one and mark the original one for deprecation in a minor release MINOR change and remove it in a later major release MAJOR (see semver FAQ entry: https://semver.org/#how-should-i-handle-deprecating-functionality)
  • If possible, do the same for attributes
  • new fields should always be added as optional.
  • Postel's Law: “Be conservative in what you do, be liberal in what you accept from others”. When you have input fields that need to be removed, mark them as unused, so they can be ignored.
  • do not change the field’s semantics.
  • do not change the field’s order.
  • do not change the validation rules of the request fields to more restrictive ones.
  • if you use collections that can be returned with no content, then answer with an empty collection and not null.
  • layout pagination support from the start.

...