Skip to main content
The G-Tateth API uses versioning to ensure backward compatibility while allowing us to introduce new features and improvements.

​
Current Versions

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

​
Versioning Strategy

​
URL-Based Versioning

API versions are specified in the URL path: 
https://api.g-tateth.com/api/v1/conversations
https://api.g-tateth.com/api/v2/conversations  # Future

​
Version Headers

You can also specify the version using headers: 
GET /api/conversations HTTP/1.1
Host: api.g-tateth.com
X-API-Version: v1
If no version is specified, the latest stable version (v1) is used by default.

​
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

If you’re using the legacy API (no version prefix), migrate to v1: Before: 
GET /api/conversations
After: 
GET /api/v1/conversations

​
Breaking Changes

We document all breaking changes in our changelog. Common changes include:
  • 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

Don’t automatically upgrade to new versions. Test thoroughly first: 
const API_VERSION = 'v1'; // Pin to specific version
const baseUrl = `https://api.g-tateth.com/api/${API_VERSION}`;

​
3. Monitor Deprecation Warnings

The API includes deprecation warnings in responses: 
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

Always test in a staging environment 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

See our changelog for detailed version history and changes.

​
Support

Questions about versioning? Contact us: