API Versioning
Understanding API versioning and migration guides
API Versioning
Learn about our API versioning strategy and how to migrate between versions.
Version Strategy
We use semantic versioning for our API:
- Major version (v1, v2): Breaking changes
- Minor version (v1.1, v1.2): New features, backward compatible
- Patch version (v1.1.1, v1.1.2): Bug fixes, backward compatible
Current Version
Current API Version: v1
All endpoints use the base URL:
https://api.awalchat.com/api/developer
Version in URL
Future versions will be specified in the URL:
https://api.awalchat.com/api/v2/developer
Current Status: We're currently on v1. When v2 is released, v1 will continue to be supported for at least 12 months.
Version Headers
You can also specify the API version using headers:
| Parameter | Type | Required | Description |
|---|---|---|---|
X-API-Version | string | No | API version (e.g., 'v1', 'v2'). Defaults to latest stable version |
Example
curl -X GET "https://api.awalchat.com/api/developer/contacts" \
-H "X-API-Version: v1" \
-H "X-Awal-Signature-256: sha256=..." \
-H "X-Timestamp: 1704124800" \
-H "X-Domain: your-workspace" \
-H "X-Client-ID: your-client-id"Deprecation Policy
Timeline
- Announcement: Deprecated features are announced 6 months in advance
- Deprecation: Feature marked as deprecated but still functional
- Removal: Feature removed after 12 months from deprecation
Deprecation Headers
Deprecated endpoints include a warning header:
HTTP/1.1 200 OK
X-API-Deprecated: true
X-API-Deprecation-Date: 2024-12-31
X-API-Sunset-Date: 2025-12-31
Warning: 299 - "This endpoint is deprecated. Use /api/v2/endpoint instead"Migration Guides
From v1 to v2 (When Available)
When v2 is released, we'll provide comprehensive migration guides:
- Breaking Changes: List of all breaking changes
- New Features: What's new in v2
- Migration Steps: Step-by-step migration guide
- Code Examples: Updated code examples for v2
Stay Updated: Subscribe to our changelog to be notified of new versions and deprecations.
Changelog
v1.2.0 (Upcoming)
- New webhook events
- Enhanced rate limiting
- Improved error messages
v1.1.0 (Current)
- Added batch operations
- New message types
- Enhanced webhook security
v1.0.0 (Initial Release)
- Core messaging API
- Contact management
- Conversation tracking
- Order management
Best Practices
Versioning Best Practices
- Pin Your Version: Always specify the API version you're using
- Monitor Deprecations: Check deprecation headers in responses
- Test Updates: Test new versions in staging before production
- Stay Updated: Subscribe to changelog notifications
- Plan Migrations: Start migration planning when deprecation is announced
Version Pinning Example
// Always pin your API version
const API_VERSION = 'v1';
const BASE_URL = `https://api.awalchat.com/api/${API_VERSION}/developer`;
// Use in all requests
const response = await fetch(`${BASE_URL}/contacts`, {
headers: {
'X-API-Version': API_VERSION,
// ... other headers
}
});Testing Different Versions
Staging Environment
Test new versions in our staging environment:
https://staging-api.awalchat.com/api/v2/developer
Staging Access: Contact support to get access to staging environment for testing new versions.
Version Support
| Version | Status | Support Until |
|---|---|---|
| v1 | Current | TBD |
| v2 | Upcoming | TBD |
Related Sections
Technical Support
Questions about API versioning?
- š§ Email: support@awalchat.com
- š¬ Live Chat: Available in the dashboard
- š± WhatsApp: Contact us directly via WhatsApp
- š Changelog: View API Changelog