Versioning

The Beamery API follows a structured versioning approach to ensure stability while continuously evolving our capabilities. Our versioning strategy allows you to build with confidence, knowing that your integrations will remain stable as we enhance the platform.

Version Format

All API endpoints include a version identifier in the URL path, following the pattern https://frontier.beamery.com/v1/endpoint. The version consists of a "v" prefix followed by a major version number, such as v1 or v2. This versioning is specified at the API level rather than per individual endpoint, providing consistency across all operations within a given version.

Stability Commitment

When using a specific API version, you can rely on our guarantee of backwards compatibility within that major version. We will not introduce breaking changes without releasing a new major version, ensuring your existing integrations continue to function as expected. While the core functionality remains stable, we may enhance the API by adding new features and endpoints to existing versions. When the time comes to sunset a version, we provide deprecation notices well in advance, giving you ample time to plan and execute your migration.

What Constitutes a Breaking Change

We take a conservative approach to defining breaking changes to protect your integrations. A new major version is required when we remove an existing endpoint, remove or rename required request parameters, or change the structure of response objects. Similarly, modifications to authentication mechanisms or alterations to error response formats are considered breaking changes. These strict guidelines ensure that your code continues to work reliably with the version you've chosen to implement.

Non-Breaking Changes

Within the same API version, we continuously improve the platform through non-breaking changes. These include adding new optional request parameters that provide additional functionality without affecting existing calls, and enriching response objects with new fields that your application can safely ignore if not needed. We regularly introduce new endpoints to expand the API's capabilities, implement performance improvements to enhance speed and reliability, and fix bugs to ensure smooth operation. These enhancements are designed to be completely backwards compatible, allowing you to benefit from improvements without modifying your code.

Version Lifecycle

Active Version

The current active version is v1, which represents our latest and most feature-rich API implementation. This version receives continuous updates including new features and enhancements, critical security updates, bug fixes, and full technical support from our team. As the primary version, v1 is where all new development occurs and where you'll find the most comprehensive functionality for integrating with Beamery's platform.

Deprecated Versions

When we release a new major version, previous versions enter a carefully managed deprecation phase lasting at least 12 months. During this period, deprecated versions continue to function but receive only critical security updates to ensure your data remains protected. We provide comprehensive migration guides that detail the changes between versions and offer step-by-step instructions for updating your integration. Additionally, deprecation warnings are automatically included in API responses, serving as gentle reminders to plan your migration.

End of Life

Following the deprecation period, versions reach their end of life and are retired from service. At this point, the version becomes inaccessible, and all requests return a specific error clearly indicating that the version has been sunset. This approach ensures a clean transition and prevents applications from unknowingly using outdated API versions. Organizations must complete their migration to a supported version before the end-of-life date to maintain uninterrupted service.

Best Practices

To ensure smooth integration with the Beamery API, we recommend following several key practices. Always specify the version explicitly in your API calls rather than relying on defaults, as this protects your integration from unexpected changes. Regularly monitor deprecation notices that appear in API responses and documentation to stay informed about upcoming changes. Before migrating to a new version, thoroughly test your integration in our sandbox environment to identify any adjustments needed. Subscribe to our developer updates to receive timely announcements about new versions and important changes. Most importantly, when new versions are announced, begin planning your migration early to avoid last-minute rushes and ensure a smooth transition.

Version Headers

Every API response includes version information in the headers to help you track and manage your API usage effectively. The X-API-Version header confirms which version is handling your request, while X-API-Deprecated indicates whether the version you're using has been marked for deprecation. When applicable, the X-API-Sunset-Date header provides the specific date when a deprecated version will be retired. These headers serve as a built-in monitoring system, allowing you to confirm the version being used, detect deprecation status programmatically, and plan migrations well before sunset dates arrive.

X-API-Version: v1
X-API-Deprecated: false
X-API-Sunset-Date: null