Versioning

From time to time, we may need to make breaking changes to our API functionality. We try very hard to avoid this, but it is sometimes necessary, e.g., to fix bugs when some users may have code that relies on the incorrect behavior.

Flacon API releases are versioned using a one-part versioning scheme: {major version}. We partially follow Semantic Versioning principles when versioning the Falcon API. The major version number is incremented when a backward-incompatible change occurs. The URLs used in the API reflect this by incorporating the major version, using the following pattern (relative to the base URL):

https://stage.tab.kitecash.in/open-api/falcon/v{major version number}

📘

Change Log

Looking for the latest changes? Check them out in the Change Log.

API Versioning Guidelines

The guideline is that for any changes in the API:

• A minor change will always be backward compatible and this does not change the major version number.
• If the version is not changing (e.g. v1), the changes will be non-breaking changes and will always be backward compatible.
• if there are breaking changes then the new version (e.g. v2) of the API will be released, for a certain period of time v1 version will also be maintained but will be marked deprecated, giving enough time for existing integrations to migrate. once all migrations are done, the V1 version of the API will be taken down.

Deprecation and Removal

The burden of supporting older versions of the API grows as our services evolve. At times we will have to deprecate and then remove certain older versions of the API. We will always give appropriate notice when version removal is necessary.

Backward-compatible changes

We consider the following changes to be backward-compatible and may therefore introduce them retroactively in old API versions:

• Adding new object attributes in JSON responses (outside of documents or query results).
• Changing the order of object attributes in JSON responses.
• Adding new prefixed metadata attributes to stored or modified documents.
• Adding new functionality to endpoints, e.g., operators, functions, and data types.
• Adding new, optional parameters to API calls.
• Adding new HTTP headers in responses.
• Adding new endpoints to the API or new methods to the existing API endpoint.