API Versioning

​

Current Versions

• v1 (Current) - Stable, production-ready API
• v2 (Coming Soon) - Next generation API with enhanced features

​

Versioning Strategy

​

URL-Based Versioning

https://api.g-tateth.com/api/v1/conversations
https://api.g-tateth.com/api/v2/conversations  # Future

​

Version Headers

GET /api/conversations HTTP/1.1
Host: api.g-tateth.com
X-API-Version: v1

​

Version Lifecycle

​

Stable Versions

• Long-term support - Maintained for at least 12 months
• Backward compatible - No breaking changes
• Security updates - Regular security patches
• Bug fixes - Critical bug fixes

​

Deprecated Versions

• 6-month notice - We provide 6 months notice before deprecation
• Migration guide - Detailed migration documentation
• Support - Limited support during deprecation period

​

Sunset Versions

• No longer supported - No updates or fixes
• May be removed - Endpoints may stop working
• Migration required - Must upgrade to supported version

​

Migration Guide

​

From v0 to v1

GET /api/conversations

GET /api/v1/conversations

​

Breaking Changes

• Endpoint paths - URL structure changes
• Request/response formats - Schema changes
• Authentication - Auth method changes
• Error codes - Error code updates

​

Best Practices

​

1. Always Specify Version

// ✅ Good - Explicit version
const response = await fetch('https://api.g-tateth.com/api/v1/conversations');

// ❌ Bad - Relies on default
const response = await fetch('https://api.g-tateth.com/api/conversations');

​

2. Pin Your Version

const API_VERSION = 'v1'; // Pin to specific version
const baseUrl = `https://api.g-tateth.com/api/${API_VERSION}`;

​

3. Monitor Deprecation Warnings

HTTP/1.1 200 OK
X-API-Version: v1
X-API-Deprecated: true
X-API-Sunset: 2025-01-01
Warning: 299 - "API version v1 will be sunset on 2025-01-01. Please migrate to v2."

​

4. Test Before Upgrading

// Staging environment
const stagingUrl = 'https://staging-api.g-tateth.com/api/v2';

// Production environment
const productionUrl = 'https://api.g-tateth.com/api/v1';

​

Version-Specific Features

​

v1 Features

• RESTful API design
• JSON request/response format
• Bearer token authentication
• Webhook support
• Rate limiting
• Pagination

​

v2 (Planned)

• GraphQL support
• WebSocket subscriptions
• Enhanced filtering
• Batch operations
• Advanced analytics

​

Changelog

​

Support

• Email: support@g-tateth.com
• Documentation: https://docs.g-tateth.com