Versioning
API versioning is crucial for maintaining backward compatibility and ensuring that changes to the API do not disrupt existing integrations. This section outlines the versioning strategy used by Verifiet and provides guidance on how to handle different versions.
Versioning Strategy
1. Semantic Versioning
- Format: Verifiet follows Semantic Versioning (MAJOR.MINOR.PATCH).
- MAJOR: Increases when there are significant changes that are not backward-compatible.
- MINOR: Increases when new features are added in a backward-compatible manner.
- PATCH: Increases for backward-compatible bug fixes or small changes.
2. Versioning in the API URL
- Format: Versions are specified in the API endpoint URLs.
- Example:
https://api.verifiet.com/v1/endpoint
- Recommendation: Always specify the version in your API requests to avoid breaking changes.
3. Deprecation Policy
- Notification: When a new MAJOR version is released, the previous version will be deprecated, but it will remain supported for a certain period (usually 6 months).
- Deprecation Warnings: When using a deprecated version, you will receive warnings in the API response headers.
- End of Life: Once the deprecation period ends, the deprecated version will be retired and no longer supported.
4. Handling Breaking Changes
- Communication: Any breaking changes will be communicated through release notes, email notifications, and updates in the documentation.
- Migration Guides: For each MAJOR version release, a migration guide will be provided to assist in transitioning to the new version.
Version History
v1.0.0 (Initial Release)
- Date: August 2, 2024
- Summary: The initial release of the Verifiet API with core functionalities including entity monitoring, onboarding, and investigation.
Best Practices for Versioning
- Always Specify the API Version: Include the version number in your API requests to ensure you are using the correct version.
- Monitor Deprecation Notices: Keep an eye on deprecation warnings in API responses and plan migrations accordingly.
- Test on New Versions: Before switching to a new MAJOR version, thoroughly test your application with the new API version in a staging environment.
- Read Release Notes: Always review the release notes for details on what has changed between versions.
Conclusion
Verifiet's API versioning strategy is designed to balance stability with the need for innovation and improvement. By following the guidelines provided here, you can ensure that your integration remains smooth and compatible across different versions of the API.
For any version-specific questions or support, please refer to our detailed release notes or contact our technical support team.