Service API Design - API Version Specification

API version specification

Release RELEASE version

The officially released api package must be the RELEASE version

eg.

1 2 3 4 5

<dependency> <groupId>cn.gov.zcy.paas.template</groupId> <artifactId>template-api</artifactId> <version>2.1.1.RELEASE</version> </dependency>

version number style

Use the " Semantic Versioning " style

Overview

The version number is composed of three segments of "MAJOR.MINOR.PATCH", and the version number adds meaning:

1. MAJOR version: [major version number] represents an incompatible change to the API, even a minor one.
2. MINOR version: [Minor version number] means that functions and features have been added in a compatible way
3. PATCH version: [patch version number] means that the bugfix has been made in a compatible way

Usage/FAQ

The version number starts with 0

• The three version numbers of XYZ all start with 0.
• 【Special attention】When the version number is "1.0.9.RELEASE", its next patch version number is "1.0.10.RELEASE"! ! !
  • Instead of "1.1.0.RELEASE", there is no full decimal here.

Initial MAJOR version

• The initial MAJOR version starts with 0, which represents the initial development stage of the business. During this process, any functional changes may occur, and the API at this time is unstable.
• Once the initial version is released to the production environment, the MAJOR version will be changed to 1, which is 1.0.0.RELEASE. is the first baseline version.

pre-release version

• A pre-release version can be denoted by immediately following the patch version with an additional hyphen followed by a series of dot-separated identifiers. Identifiers must contain only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifier cannot be empty. Numeric identifiers must not contain leading zeros.
• A pre-release version has a lower priority than the associated normal version.
• A pre-release version indicates an unstable version that may not meet the expected compatibility requirements expressed by its associated normal version. Example: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92

{{o.name}}

{{m.name}}