Page History

...

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

• 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 bug fixing purposes
• public (x.y.z) API versions for usage in commercial contexts. Public API versions only have API version number x.y.z (semver 2.0), no extension. The public API can have one of two maturity states: 
  • initial (x=0) - indicating that the API is still not fully stable
  • stable (x=0x>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 process is illustrated in the following figure.

...

Note: in CAMARA v1.0.0 is considered the first stable public API, while API versions v0.y.z can be public, but are considered unstable (initial).

Precedence example:     0.10.0 < 1.0.0 < 2.0.0 < 2.1.0 < 2.1.1 < 3.0.0.

...

• Once a stable public API version is created, the API version in the URL shall ONLY contain "vx", and never include an extension.
• ExceptionIMPORTANT: For initial public API versions 0.y.z, the MINOR number may MUST 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 for an alpha API version 2.y.z-alpha.1, the version in the URL is v2alpha1, e.g. {apiRoot}/qod/v2alpha1.

API name

The API name is the segment in the url field in the OAS definition file before the segment holding the API version.

...

...

Precedence examples for API versions throughout the release process:

...

• 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 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+11.0.0 → 1.0MINOR: 0.9.0 → 0.9.1-alpha.1 → ... → 10.09.1-alpha.m → 10.09.1-rc.1 → ... → 10.09.1-rc.n → 10.09.1 (next stable initial public version)
  • MINOR: 1.0.0 → 1.1.0-alpha.1 → ... → 1.1.0-alpha.m → 1.1.0-rc.1 → ... → 1.1.0-rc.n → 1.1.0 (next stable public version)
  • MAJOR: 0.9.1 → 0.10.0-alpha.1 → ... → 0.10.0-alpha.m → 0.10.0-rc.1 → ... → 0.10.0-rc.n → 0.10.0 (next initial public version)
  • MAJOR: 1.1.0 → 2.0.0-alpha.1 → ... → 2.0.0-alpha.m → 2.0.0-rc.1 → ... → 2.0.0-rc.n → 2.0.0 (next stable public 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
      • 2.0.0 → 2.0.1-alpha.1 → ... → 2.0.1-alpha.m → 2.0.1-rc.1 → ... → 2.0.1-rc.n → 2.0.1 (next stable public version)
    • apply a apply a short process to create a maintenance-release of the public API version.

  ...

  Semantic versioning on breaking changes:

  • breaking changes imply a major MAJOR version increment (that's the fundamental part)
  • semver FAQ entry: https://semver.org/#if-even-the-tiniest-backward-incompatible-changes-to-the-public-api-require-a-major-version-bump-wont-i-end-up-at-version-4200-very-rapidly

  ...

  • deleting operations or actions on a resource. For example: POST requests on a resource are no longer accepted.
  • adding a new mandatory input parameters. For example: now, to register a resource, a new required field must be sent in the body of the request.
  • modifying or removing a mandatory parameter in existing operations (resource verbs). For example, when consulting a resource, a certain field is no longer returned, or a field that was previously a string is now numeric. (breaks existing payloads)
  • modifying or removing an endpoint (breaks existing queries)
  • changing input parameters from optional to mandatory. For example: when creating a Person resource, the age field, which was previously optional, is now mandatory.
  • modifying responses to existing operations.
  • adding new responses to existing operations. For example: creating a resource can return a 412 response code.

  ...

  • never change an endpoint name; instead, add a new one and mark the original one for deprecation in a MINOR change and remove it in a later 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.

  How to avoid breaking changes (API consumer) ?

  • tolerant reader: if it does not recognize a field when faced with a response from a service, do not process it, but record it through the log (or resend it if applicable).
  • ignore fields with null values.
  • variable order rule: DO NOT rely on the order in which data appears in responses from the JSON service, unless the service explicitly specifies it.
  • clients MUST NOT transmit personally identifiable information (PII) parameters in the URL. If necessary, use headers

  Make the information available:

  ...

  • 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.

  How to avoid breaking changes (API consumer) ?

  • tolerant reader: if it does not recognize a field when faced with a response from a service, do not process it, but record it through the log (or resend it if applicable).
  • ignore fields with null values.
  • variable order rule: DO NOT rely on the order in which data appears in responses from the JSON service, unless the service explicitly specifies it.
  • clients MUST NOT transmit personally identifiable information (PII) parameters in the URL. If necessary, use headers

  Make the information available:

  • provide an access to the new API version definition file (via a link or dedicated endpoint)
  • if possible, do the same to obtain the currently implemented API version definition file

  Bearing in mind that APIs are continually evolving and certain operations will no longer be supported, the following considerations must be taken into account:

  • Agree to discontinue an API version with consumers.
  • Establish the obsolescence of the API in a reasonable period (6 months).
  • Monitor the use of deprecated APIs.
  • Remove deprecated APIs documentation.
  • Never start using already deprecated APIs.

  ...