Skip to main content

API Versioning

Learn about the Audian API versioning strategy and how to manage different API versions.

Overview​

The Audian API uses URL-based versioning to ensure backward compatibility while allowing for improvements and new features. The API version is included in every request URL.

Current Version​

v2 (Current)​

Status: Active and stable URL: https://api.audian.com:8443/v2

The current production version with all latest features.

Version in URL​

Every request includes the version:

# v2 request
GET https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/users

Versioning Policy​

We follow Semantic Versioning principles:

Major Version (v1, v2, ...)​

Breaking changes:

  • Request/response format changes
  • Removed endpoints
  • Required parameter changes
  • Authentication changes

Behavior: Old versions continue to work during transition period (typically 12 months)

Minor Version​

New features (backward compatible):

  • New endpoints
  • New optional parameters
  • New response fields

Behavior: Automatic, no migration needed

Patch Version​

Bug fixes (backward compatible):

  • Security fixes
  • Performance improvements
  • Bug corrections

Behavior: Automatic, deployed without notice

Version Support​

VersionStatusNotes
v2ActiveCurrent production version

Backward Compatibility​

What We Promise​

Within a major version:

  • Existing endpoints remain available
  • Response fields are additive (new fields may be added)
  • Request parameters stay compatible
  • Authentication methods don't change

What You Must Handle​

  • New optional response fields
  • Changes to error handling
  • Rate limit adjustments

Making Requests​

Always include the version in your API requests:

curl -X GET "https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/users" \
  -H "X-Auth-Token: YOUR_API_KEY"

Code Examples​

Python​

import requests

API_KEY = 'your_api_key'
ACCOUNT_ID = 'your_account_id'
BASE_URL = 'https://api.audian.com:8443/v2'

response = requests.get(
    f'{BASE_URL}/accounts/{ACCOUNT_ID}/users',
    headers={'X-Auth-Token': API_KEY}
)

Node.js​

const API_KEY = 'your_api_key';
const ACCOUNT_ID = 'your_account_id';
const BASE_URL = 'https://api.audian.com:8443/v2';

const response = await fetch(
  `${BASE_URL}/accounts/${ACCOUNT_ID}/users`,
  {
    headers: { 'X-Auth-Token': API_KEY }
  }
);

Best Practices​

Do's ✓​

  • Always include the version in the URL
  • Check the changelog for updates
  • Test with new versions before migrating
  • Handle new response fields gracefully

Don'ts ✗​

  • Don't hardcode version-specific behavior
  • Don't ignore deprecation notices
  • Don't assume endpoints will never change

Staying Informed​

Next Steps​