Learn about Falcon API versioning, including versioning strategy, backward-compatible changes, deprecation policies, and best practices for seamless integration and updates.
Falcon utilizes a versioned API to ensure stability and backward compatibility while introducing new features and improvements. Understanding the versioning strategy is essential for developers to maintain seamless integrations.
Versioning Strategy
Falcon follows a one-part versioning scheme: v{major_version_number}. This approach is inspired by Semantic Versioning principles.
- Major Version (vX): Incremented when backward-incompatible changes are introduced.
- Minor Changes: Backward-compatible enhancements that do not alter the major version.
API URLs incorporate the major version number, e.g., https://stage.tab.kitecash.in/open-api/falcon/vX.
Backward-Compatible Changes
Certain modifications are considered backward-compatible and may be introduced without incrementing the major version:
- 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.
- Introducing new functionality to endpoints, e.g., operators, functions, and data types.
- Adding new, optional parameters to API calls.
- Introducing new HTTP headers in responses.
- Adding new endpoints to the API or new methods to existing endpoints.
Deprecation and Removal
As Falcon evolves, older API versions may be deprecated and eventually removed:
- Deprecation: Older versions are marked as deprecated, signaling that they will no longer receive updates or support.
- Removal: After a grace period, deprecated versions are removed to reduce maintenance overhead.
Developers are encouraged to migrate to newer versions promptly to ensure continued support and access to new features.
Best Practices for Developers
To maintain compatibility and leverage the latest features:
- Use Latest Versions: Integrate the latest API versions to access new functionalities and improvements.
- Monitor Deprecations: Be aware of deprecated versions and plan migrations accordingly.