API Versioning Policy

This document outlines the GxP API versioning strategy, including how we release new versions, deprecate old ones, and maintain documentation across different API versions.

Version Naming Convention

GxP API versions follow semantic versioning principles:

• Major versions (v1, v2, v3): Contain breaking changes that require client updates
• Minor versions (v1.1, v1.2): Add new features while maintaining backward compatibility
• Patch versions: Bug fixes and security updates (not reflected in API version)

Current Versions

Version	Status	Support Until	Documentation
v1	Current	Ongoing	View Docs

Version Lifecycle

Each API version goes through the following lifecycle stages:

┌─────────────┐    ┌────────────┐    ┌──────────────┐    ┌─────────────┐
│   Preview   │ -> │   Stable   │ -> │  Deprecated  │ -> │   Retired   │
│  (Beta)     │    │  (Current) │    │ (Legacy)     │    │  (Removed)  │
└─────────────┘    └────────────┘    └──────────────┘    └─────────────┘

Stage Definitions

Preview (Beta)

• New features being tested before general availability
• API may change without notice
• Not recommended for production use
• Documentation marked with "Beta" badge

Stable (Current)

• Production-ready and recommended for use
• Backward-compatible changes only
• Full documentation and support
• Active maintenance and bug fixes

Deprecated (Legacy)

• Still functional but no longer recommended
• Security fixes only, no new features
• Documentation displays deprecation warning
• Migration guide provided to newer version

Retired (Removed)

• No longer available
• API endpoints return error responses
• Documentation archived for reference only

Deprecation Timeline

When a new major version is released:

Timeline	Action
Day 0	New version (vN+1) becomes "Current"
Day 0	Previous version (vN) becomes "Deprecated"
+6 months	Deprecation warnings in API responses
+12 months	Previous version (vN) retired

Deprecation Notice

We provide at least 12 months notice before retiring any API version. You will see deprecation warnings in both the documentation and API responses during this period.

Breaking Changes

A change is considered "breaking" if it:

• Removes an existing endpoint
• Removes or renames a response field
• Changes the data type of a response field
• Adds a new required request parameter
• Changes authentication requirements
• Modifies error response formats

Non-Breaking Changes

The following changes are NOT considered breaking:

• Adding new optional request parameters
• Adding new response fields
• Adding new endpoints
• Adding new enum values
• Improving error messages
• Performance improvements

Documentation Versioning

Using the Version Selector

Use the version dropdown in the navigation bar to switch between different API version documentation. The dropdown shows:

• Current version: Latest stable API documentation
• Previous versions: Documentation snapshots for older API versions
• Version Policy: This page

URL Structure

Documentation URLs follow this pattern:

Current version:  https://docs.gramercy.cloud/guides/attendee-management
Version 1.0:      https://docs.gramercy.cloud/v1.0/guides/attendee-management

Migration Guides

When upgrading between API versions, refer to our migration guides:

• Migrating to v2 (Coming Soon) - Guide for upgrading from v1 to v2

API Specification Files

Versioned OpenAPI specifications are available for programmatic access:

Version	OpenAPI Spec	AsyncAPI Spec
v1 (Current)	openapi-v1.json	asyncapi-v1.json

Notifications

Staying Informed

To stay informed about API version changes:

1. Watch the GitHub repository for release announcements
2. Subscribe to the changelog feed
3. Check the API response headers for deprecation warnings

Deprecation Headers

When using a deprecated API version, responses include warning headers:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Jan 2026 00:00:00 GMT
Link: <https://docs.gramercy.cloud/migration/v1-to-v2>; rel="deprecation"

Support

If you have questions about API versioning or need assistance migrating:

• GitHub Issues: Report issues or ask questions
• Documentation: Check the migration guides and changelog
• Email: Contact technical support for enterprise customers

Changelog

For a detailed list of changes in each version, see the API Changelog.