API versioning policy

Versioning

Due to integration maintenance, SecuTix public web services are versioned.

A public (available in production, and not being the active one, see below) version of an API never changes and is frozen.

Vocabulary

Active version

  • The version with the highest number.
  • Used by SECUTIX own systems.
  • Contract may change, always in a retro-compatible way.
  • Can be used by third-parties.

Latest version

  • The version with number just below the active version.
  • Contract is frozen.
  • Recommended use for third parties.

Deprecated versions

  • Versions still supported by SECUTIX.
  • Contract is frozen.

End of life versions

  • Those versions maybe decommissioned anytime.
  • Please consider using the latest version.
  • Contract is frozen.

Numbering versions

Public APIs are versioned according to the following pattern:

major.minor

That means that contact 2.20 means : major : 2, minor : 20

(Clearly, we are not using the major/minor numbers as they are usually used)

Changing version

  1. The active version may be subject to minor, retroc-compatible changes, without creation of a new version.
  2. In case of non retro-compatible change (see below): a new version is generated, increasing the minor number.
  3. In case of deep refactoring of a service, a new version is produced, a new version is generated, increasing the major number.

Retro-compatible changes

A retro-compatible change is:

  • Adding a method in a service
  • Adding a nullable attribute in a DTO. Passing the null value must not change the behavior of the interface.
  • Adding a value to an enumerated field.

Non-retro-compatible changes

A non-retro compatible change is any other change, including:

  • Changing signature of a method (adding or removing a parameter)
  • Renaming a field in a DTO
  • Removing a field in a DTO
  • Adding a not-nullable field in a DTO (boolean, int...)
  • Adding a field which default value is changing the behavior of the interface.