Versioning | Fynapse Documentation

Overview

This article provides information on how the API specification is versioned.

We devised the API versioning policy to facilitate the safe release of new features and provide a safeguard against breaking your integrations.

There are two categories of changes to the Fynapse API:

Non-breaking changes - this means the API endpoint changes, but the change will not affect your existing integration and therefore you don’t need to alter your integrations with the API.
Breaking changes - this means the API endpoint changes in such a way that you will need to amend your integration with the API.

API Changes

The table below outlines what is considered a breaking change or a non-breaking change. Any breaking changes will require a new version, while non-breaking changes do not require the API version to change.

Area	Non-Breaking Change	Breaking Change
HTTP endpoints and headers	- Introducing new resource and its API - New API Endpoint for a resource - New VERB on an existing endpoint - Support of a new Content Type - Add optional header	- HTTP endpoint removal - Content Type support removal - Removal of a required header
Request schema, including HTTP path and query parameters	- New optional field or parameter - New required field or parameter with a default value - Add enum value to an enum field - Relaxing the validation rules on a field or value (e.g. allow for a bigger number)	- Removal of field or parameter - Adding a new mandatory field or parameter without a default value - Adding stricter validations to an already existing parameter of the field
Request Processing	- Changing error response messages	- An interpretation of a field or a combination of field changes
Response Body schema	- Adding a new field in the response schema	- Changing the data type of a response field
Response Headers	- Adding a new response header - Adding a new status code to the response	- Change of a response status - Removal of a response header

API Versioning Scheme and Identifiers

There is no global API version defined for Fynapse APIs. The APIs are versioned per REST resource and only breaking changes mandate the version number to increase.

The version number of each REST resource is included in the path:

/api/v{versionNumber}/resource

e.g.

/api/v2/security/group

API Changelog

Any API changes, both breaking and non-breaking, are documented in the API Changelog and, if necessary in accompanying end-user documentation.

API Version Lifecycle

When a breaking change is introduced and a new version of the API is released, the previous version of the API gets a deprecation and removal date. The old versions of APIs will be supported for a total of 15 months after a new version of API was introduced.

There are 4 significant milestones in the API lifecycle:

Milestone	API state
API version was released	STABLE
New version of API was released	STABLE - not preferred
A release of a new Fynapse version 12 months after the previous milestone	STABLE - removed soon
A release of a new Fynapse version 90 days after the previous milestone	REMOVED

Below is a sample example of an API version lifecycle and a schedule of Fynapse releases:

Duration	Fynapse version	API version 1	API version 2
	2025.1.1	STABLE
12 months	2025.2.1	STABLE - not preferred	STABLE
	2025.2.2
	2025.2.3
	2025.3.x
	2025.4.x
90 days	2026.2.1	STABLE - removed soon
	2026.2.2
	2026.2.3
	2026.3.1	REMOVED

Fynapse will support a previous API version for at least 90 days after the introduction of a new version of the API. The schedule of API versions deprecation and removal is published in Release Notes.

API Version Statuses

API version state: STABLE

When API is in Stable state it will be functional and fully supported by Fynapse.

API version state: STABLE - not preferred

The API remains functional. All the responses are enriched with a Sunset Header that will contain a timestamp of the expected decommission date expressed as HTTP-date. The advertised timestamp will be calculated as 15 months after the timestamp of a release of the new version of the API.

Fynapse documentation will be adjusted to endorse the new version of the API. A clear indication will be provided that this version of the API should not be used for new integrations as well as any existing integrations using this version should be scheduled to migrate to a newer version.

API version state: STABLE - removed soon

API remains functional. The Sunset header remains with the original date.

Fynapse documentation will warn about the pending API removal.

API version state: REMOVED

API is no longer functional. All endpoints for this version respond with 410 (Gone) status code to any authenticated request to a particular version of a resource for a period of 90 days.

Fynapse will no longer include documentation about the removed APIs.