Skip to main content

Versioning

Our API is designed to evolve over time, and we are committed to maintaining a stable and predictable experience for our developers. To achieve this, we use versioning to manage changes and ensure compatibility.

Current version​

The current version of our API is prefixed with v1/. For example: https://api.light.dev/v1/account.

Approach​

Here’s how we handle different types of changes to the API:

Backward-compatible changes​

These include adding new endpoints, new fields to existing responses, or new optional parameters to existing requests. To ensure your integration remains stable, please design it to gracefully handle unknown keys in API responses. These changes will be made within the current version (v1) and will not require any modification from your side.

Backward-incompatible changes​

These changes include removing or renaming existing endpoints, changing the structure of responses or requests, or any changes that would require modifications to your integration. When such changes are necessary, they will be introduced in a new version (e.g., v2, or another version header to be designed in the future). We will provide detailed documentation and migration guides to help you transition to new versions as needed.

Deprecation policy​

When we release a new version, the previous version will enter a deprecation period. During this period:

  • The deprecated version will continue to function as expected.
  • We will provide detailed documentation and migration guides to help you transition to the new version.
  • The deprecation period will last for at least 6 months, giving you ample time to make necessary adjustments.

Notifications and support​

  • Notifications: We will notify you of any upcoming changes via our developer portal, email updates, and in our documentation.
  • Support: Our team is be available to assist you with any questions or issues you encounter during the transition to a new version.

We are committed to making API updates as seamless as possible and will provide the resources and support you need to keep your integration running smoothly, while also taking advantage of new features and improvements.