API Versioning
Versioning Principles
SECUTIX public web services and webhooks are versioned.
The active version is always the one with the highest version number.
The public documentation always refers to the active version. YAML specification files for previous versions remain available for download.
Versions follow this pattern:
major_minor
If the minor version is not provided, it is implicitly 0.
Examples:
s360/v3/contacts→contactsresource, major 3, minor 0- a version written
v3_2reads major 3, minor 2
The active version of every s360 service is v3, written without a minor number. All the endpoints in this documentation use it.
Version evolution may differ per system. (See Understanding Endpoint URLs)
Version Changes
- Minor, backward-compatible improvements may be applied to the active version without creating a new version.
- Non backward-compatible changes (see definition below) require a new version with the minor number increased.
- Major redesigns or structural refactoring require a new version with the major number increased.
How You Are Informed of Changes
- Every release is listed in the Change Log with its date and the APIs it affects. This includes the backward-compatible improvements applied to the active version, so you can see what changed even when the version number did not.
- A new version is announced in the Change Log when it is published. The previous version keeps working, and its specification remains available for download.
- Decommissioning a version is announced at least 6 months in advance, as set out in the Terms and Conditions. Only an urgent security or compliance reason can shorten this notice.
Backward Compatibility
The following changes are considered backward compatible and should already be handled by integrators during implementation:
- Adding new fields (optional fields in response objects)
- Adding new endpoints (new capabilities without modifying existing ones)
- Extending enums (adding new possible values)
- Performance or stability improvements (without modifying data structures)
Any other type of change is considered non-backward compatible, including:
- Removing an endpoint
- Renaming a field in a schema
- Removing a field in a schema
- Adding a mandatory parameter to an endpoint