API Versioning

​

API Versioning Strategy

​

Version Format

curl -X GET "https://api.hixbe.com/payment/payment_intents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Xerobi-Version: 2026-01-01"

​

Current Version

​

Version Lifecycle

​

Version States

​

Deprecation Timeline

1. Active Period: 12 months of full support
2. Deprecation Notice: 3 months advance warning
3. Deprecated Period: 6 months of limited support
4. Sunset: Version retired

​

Backward Compatibility

​

What We Guarantee

• Existing API endpoints remain functional
• Request/response formats are stable
• Breaking changes are introduced in new versions only
• Deprecation notices provided 3+ months in advance
• Migration guides provided for major changes

​

What May Change

• New optional fields added to responses
• New endpoints added
• New optional parameters added to requests
• Performance improvements
• Bug fixes that don’t change behavior

​

Version Headers

​

Required Headers

# Always include the version header
-H "Xerobi-Version: 2026-01-01"

​

Version Detection

1. Return a 400 Bad Request error
2. Include a message specifying the required header

{
  "success": false,
  "error": {
    "code": "MISSING_VERSION_HEADER",
    "message": "The Xerobi-Version header is required",
    "details": {
      "required_header": "Xerobi-Version",
      "current_version": "2026-01-01"
    }
  }
}

​

Version-Specific Features

​

Version 2026-01-01 Features

​

Migration Guide

​

Upgrading to 2026-01-01

# Test with new version
curl -X GET "https://sandbox.api.hixbe.com/payment/payment_intents" \
  -H "Authorization: Bearer YOUR_SANDBOX_KEY" \
  -H "Xerobi-Version: 2026-01-01"

// Update your API client
const client = new HixbeClient({
  apiKey: process.env.HIXBE_API_KEY,
  version: '2026-01-01'  // Update this line
});

​

Version History

​

Best Practices

​

Version Management

• Always specify the version header explicitly
• Use the latest version for new integrations
• Test version upgrades in sandbox first
• Monitor deprecation notices in your dashboard
• Keep your integration documentation updated

​

Code Organization

// Centralized version management
const HIXBE_CONFIG = {
  version: '2026-01-01',
  baseUrl: process.env.NODE_ENV === 'production'
    ? 'https://api.hixbe.com'
    : 'https://sandbox.api.hixbe.com'
};

class HixbeClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.version = HIXBE_CONFIG.version;
    this.baseUrl = HIXBE_CONFIG.baseUrl;
  }

  async request(endpoint, options = {}) {
    const headers = {
      'Authorization': `Bearer ${this.apiKey}`,
      'Xerobi-Version': this.version,
      'Content-Type': 'application/json',
      ...options.headers
    };

    return fetch(`${this.baseUrl}${endpoint}`, {
      ...options,
      headers
    });
  }
}

# Configuration management
HIXBE_CONFIG = {
    'version': '2026-01-01',
    'base_url': os.getenv('HIXBE_BASE_URL', 'https://api.hixbe.com')
}

class HixbeClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.version = HIXBE_CONFIG['version']
        self.base_url = HIXBE_CONFIG['base_url']

    def _get_headers(self):
        return {
            'Authorization': f'Bearer {self.api_key}',
            'Xerobi-Version': self.version,
            'Content-Type': 'application/json'
        }

​

Support and Migration Help