CreoleCentric Logo
CreoleCentric Logo
Sign In

API Versioning & Stability Policy

Semantic Versioning with Extended Support

We use semantic versioning for all API changes. Breaking changes require new major versions (e.g., v1 → v2). We support 2 major versions simultaneously, giving you a 7-month migration window.

How We Version Our API

Semantic Versioning Format

MAJOR.MINOR.PATCH
MAJOR
Breaking changes that require code updates
MINOR
New features, backwards compatible
PATCH
Bug fixes, backwards compatible

Breaking Changes = New Major Version

When we need to introduce breaking changes, we release a new major version (e.g., v2.0.0). The old version continues to work alongside the new version during the migration period.

Key principle: You never wake up to broken API calls. Old versions remain supported through a defined deprecation period, giving you time to migrate on your schedule.

Version Lifecycle

1

Staging Release (30 Days)

New versions are first released to our staging environment (staging-api.creolecentric.com). This gives you a full month to test the new version with your code before it reaches production.

During this phase:
  • Full documentation and migration guides published
  • Email notification sent to all API key holders
  • Developer support available for migration questions
2

Production Deployment (15 Days Dual Support)

The new version is deployed to production. Both the old and new versions are active and fully supported. You can migrate when ready during this overlap period.

During this phase:
  • Both versions receive full support and bug fixes
  • You can switch between versions by changing the API endpoint
  • Final reminder email sent 7 days before deprecation begins
3

Deprecation Period (6 Months)

The old version is marked as deprecated but continues to function normally. This gives you 6 months to complete your migration.

During this phase:
  • Old version continues to work without interruption
  • Critical security fixes applied to deprecated version
  • Monthly reminder emails about upcoming sunset
  • New features only added to current version
4

Version Sunset

After 7+ months total (30 days staging + 15 days overlap + 6 months deprecation), the old version is retired. API calls to the old version will return a 410 Gone status with migration instructions.

Total Migration Window: 7+ months

From the moment a new version is announced in staging, you have over 7 months to migrate before the old version sunsets.

Breaking vs. Non-Breaking Changes

Breaking Changes (Require New Major Version)

  • •Removing or renaming endpoints
  • •Removing or renaming request/response fields
  • •Changing field types (string → number, etc.)
  • •Making optional fields required
  • •Changing authentication methods
  • •Changing error response formats
  • •Changing rate limit behavior

Non-Breaking Changes (Same Version)

  • •Adding new endpoints
  • •Adding optional request parameters
  • •Adding new response fields
  • •Making required fields optional
  • •Bug fixes that restore documented behavior
  • •Performance improvements
  • •Documentation updates

API Environments

Production

Live
Base URL:https://api.creolecentric.com/v1

Stable production environment for all live applications.

Staging

Coming Soon
Base URL:https://staging-api.creolecentric.com/v1

Pre-production environment for testing new API versions before they go live.

Stay Informed About Version Changes

We'll keep you updated every step of the way:

Email Notifications
Sent to all API key holders when new versions are announced, 7 days before deprecation, and monthly during deprecation period
API Changelog
Detailed documentation of all API changes with migration guides
Response Headers
Deprecated endpoints include Sunset and Deprecation headers
← Back to Developer Portal