Skip to main content

​
API Versioning

Our API uses versioning to ensure backward compatibility while introducing new features and improvements. Understanding our versioning approach helps you build resilient integrations.

​
Current Version

The dKit API is currently at version v1. All endpoints use the version prefix in the URL path:
  • https://api.dkit.xyz/v1/quote
  • https://api.dkit.xyz/v1/track
  • https://api.dkit.xyz/v1/tokens
  • https://api.dkit.xyz/v1/providers

​
Version Headers

API responses include version information in custom headers:
HeaderDescriptionExample
x-api-versionCurrent API versionv1
x-api-versionsAvailable API versionsv1

​
Deprecation Policy

We follow a structured deprecation process to give developers ample time to migrate to newer API versions when they become available.

​
Deprecation Notifications

When an API version is scheduled for deprecation, we will:
  1. Announce the deprecation at least 6 months in advance
  2. Include deprecation headers in API responses
  3. Provide migration guides and documentation
  4. Send notifications to registered developers

​
Planned Deprecation Headers

When deprecation is active, API responses will include: 
HTTP/1.1 200 OK
Warning: 299 - "This API version is deprecated and will be removed soon"
x-api-deprecated: true
x-api-sunset-date: 2026-06-01T00:00:00Z
HeaderDescription
WarningHTTP standard deprecation notice (code 299)
x-api-deprecatedBoolean indicating deprecation status
x-api-sunset-dateISO 8601 date when version will be removed

​
Sunset Timeline

Our standard deprecation timeline ensures you have sufficient time to migrate:
1

Announcement Phase

Duration: 6 months before deprecation

New version released, documentation updated, migration guides published

2

Deprecation Phase

Duration: 6-12 months

API marked as deprecated, warning headers included in responses

3

Sunset Phase

Duration: 30 days before removal

Final notices sent, increased warning visibility

4

Removal

API version removed, requests return 410 Gone status

​
Handling Deprecation

​
Best Practices

  • Monitor Headers
  • Error Handling
  • Version Tracking
// Check for deprecation warnings
fetch('https://api.dkit.xyz/v1/quote', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(quoteRequest)
})
.then(response => {
  // Check deprecation status when available
  if (response.headers.get('x-api-deprecated') === 'true') {
    const sunsetDate = response.headers.get('x-api-sunset-date');
    console.warn(`API v1 is deprecated. Sunset date: ${sunsetDate}`);
    // Trigger migration workflow
  }
  
  // Check for warning header
  const warning = response.headers.get('Warning');
  if (warning && warning.includes('299')) {
    console.warn(`API Warning: ${warning}`);
  }
  
  return response.json();
});

​
Migration Strategy

  1. Early Detection: Monitor deprecation headers in your production environment
  2. Gradual Migration: Test new versions in staging before production deployment
  3. Feature Flags: Use feature flags to switch between API versions
  4. Monitoring: Track API version usage and deprecation warnings in your logs

​
Version Compatibility

​
Breaking Changes

Breaking changes are only introduced in major version updates (e.g., v1 → v2):
  • Removed endpoints
  • Changed required parameters
  • Modified response structures
  • Authentication changes

​
Non-Breaking Changes

These changes can occur within the same version:
  • New optional parameters
  • Additional response fields
  • New endpoints
  • Performance improvements
  • Bug fixes

​
Example Response

A deprecated API response will look like: 
HTTP/1.1 200 OK
Content-Type: application/json
Warning: 299 - "This API version is deprecated and will be removed soon"
x-api-version: v1
x-api-versions: v1, v2
x-api-deprecated: true
x-api-sunset-date: 2026-06-01T00:00:00Z
Date: Mon, 01 Dec 2025 12:00:00 GMT

...

​
Notifications

Stay informed about API changes:
Important: Always implement proper error handling to ensure your integration remains robust.