Boya API Versioning Guide

Boya uses versioning to ensure smooth updates to our API without breaking existing integrations. This guide will explain how Boya API versioning works, how to request a specific version, and the best practices for managing upgrades.

Why Versioning?

As Boya evolves, we may introduce new features, make improvements, or fix bugs that change the behavior of the API. To avoid disrupting existing integrations, we use versioning to allow clients to specify which version of the API they wish to use.

Versioning Format

Boya follows a standard versioning pattern in the format v1, v2, v3, etc. The version number is included in the base URL of all API requests. When a new major version is released, it will be denoted by incrementing the version number.

Example Base URLs by Version:

v1: https://api.boyahq.com/v1
v2: https://api.boyahq.com/v2

How to Specify a Version

You can specify which version of the Boya API you want to use by including the version in the API URL. If no version is specified, the latest version of the API will be used by default.

Example Request for v1:

GET https://api.boyahq.com/v1/teams

### Example Request for v2:

```bash
GET https://api.boyahq.com/v2/teams

Backward Compatibility

Boya aims to maintain backward compatibility within each major version. Minor updates and bug fixes within a version (v1.x) will not introduce breaking changes. However, major version changes (e.g., from v1 to v2) may introduce breaking changes, which will be documented in the changelog.

Deprecation Policy

When we introduce a new major version, the older versions of the API may eventually be deprecated. Boya will follow a deprecation process to ensure a smooth transition:

Deprecation Announcement: We will announce the deprecation of an API version in advance, giving you sufficient time to upgrade.
Deprecation Warnings: You may start seeing warnings in the response headers of the deprecated API version to inform you of upcoming changes.
End of Life (EOL): After the deprecation period, the old API version will be retired, and all requests to that version will fail.

Deprecation Timeline Example:

• Announcement Date: May 1, 2024 • Deprecated Version: v1 • End of Life Date: May 1, 2025

Best Practices for Version Management

Monitor API Changes: Keep an eye on our changelog and any announcements about new versions or deprecations. We’ll provide details about changes and how to migrate.
Test New Versions: When a new version is released, test your integration in a sandbox environment using the new version’s base URL before moving to production.
Use the Latest Version: While we maintain older versions for a period of time, we recommend using the latest version of the API to take advantage of new features and improvements.
Graceful Error Handling: Ensure your application handles errors gracefully, especially in the case of API deprecations or version changes.

Versioning FAQs

How do I know when a new version is released?

You can subscribe to our API changelog or check the Boya API Dashboard for updates on new releases and deprecations.

Will my application break when a new version is released?

No, your application will not break if you are specifying a version in your requests. If a breaking change is introduced in a new major version, you can continue using the older version until you’re ready to upgrade.

How long will deprecated versions be supported?

Typically, we support deprecated versions for at least 12 months after the deprecation announcement. The exact timeline will be communicated in the deprecation notice.

Conclusion

API versioning ensures that Boya can continue to improve while maintaining stability for existing integrations. By following the guidelines above, you can ensure your application remains compatible with the Boya API as it evolves. If you have any questions or concerns, feel free to reach out to our support team.