HomeGuidesAPI ReferenceChangelog
Terms of Use
API Reference
Terms of Use

Backward compatibility

This document outlines our approach to maintaining backward compatibility for our API. Our goal is to ensure a stable and reliable experience for developers while evolving our API to meet future needs.

Key Principles

  1. Avoiding Breaking Changes: We prioritize maintaining existing functionality to ensure existing integrations continue to work without requiring changes.
  2. Non-removal of Data: Any enrichment of JSON responses will be additive; we will not remove data fields from responses.
  3. Versioning of Endpoints: Introduction of new endpoint versions (e.g., v2, v3, v4) will be done to evolve the API. Previous versions will be deprecated but remain operational for a period.
  4. Deprecation Notice: Developers will receive at least 6 months' notice before we cease support for a deprecated endpoint version.

Versioning Strategy

Introducing New Versions

  • New versions of an endpoint will be introduced as v2, v3, etc.
  • These versions may introduce new functionality or modify existing behavior.

Simultaneous Operation

  • Two versions of one endpoint can operate simultaneously.
  • This allows developers to transition to the newer version at their convenience.

Deprecation Process

  1. Announcement: When a version is deprecated, an announcement will be made via official channels.
  2. Transition Period: The deprecated version will remain operational for at least 6 months post-announcement.
  3. Support: During the transition period, support will be provided for both the deprecated and new versions.
  4. Cease of Support: Post the transition period, the deprecated version will no longer be supported or operational.

Guidelines for Developers

  1. Stay Informed: Subscribe to our developer newsletter and announcement channels to stay informed about new versions and deprecations.
  2. Plan for Migration: Once a deprecation notice is received, plan and execute the migration to the newer version within the 6-month period.
  3. Test New Versions: Thoroughly test your integration with the new version before migrating to ensure a seamless transition.
  4. Feedback Loop: Provide feedback on new versions or any challenges faced during migration. This helps us to improve the API.

Best Practices

  1. Regularly review the API documentation for updates.
  2. Design your integration to be flexible to accommodate new fields in JSON responses.
  3. Monitor API deprecation announcements and proactively plan for migrations.