API Versioning

In API Requests

There are two ways to specify which API version you want to use:

1. URL Path (Recommended)

Include the version in the URL path:

// Example request with version in URL path
https://api.telesoft.us/v2023-04-30/patients/pat_1a2b3c4d5e6f

2. Accept Header

Specify the version in the Telesoft-Version header:

// Example request with version in header
GET /patients/pat_1a2b3c4d5e6f HTTP/1.1
Host: api.telesoft.us
Authorization: Bearer YOUR_API_KEY
Telesoft-Version: 2023-04-30

Using the SDK

When using the Telesoft SDK, you can specify the API version during initialization:

// JavaScript/TypeScript SDK
const telesoft = new TelesoftAI({
  apiKey: 'YOUR_API_KEY',
  environment: 'production',
  apiVersion: '2023-04-30'  // Specify the version you want to use
});

// Python SDK
from telesoft.healthcare import TelesoftAI

telesoft = TelesoftAI(
    api_key="YOUR_API_KEY",
    environment="production",
    api_version="2023-04-30"  # Specify the version you want to use
)

If you don't specify a version, the SDK will use the latest stable version by default.

Breaking Changes (Require New Version)

• Removing or renaming fields in API responses
• Changing the type or format of existing fields
• Adding required request parameters
• Removing API endpoints
• Changing the URL structure or resource naming
• Modifying the behavior of existing functionality in a way that could break existing integrations

Non-Breaking Changes (No Version Change)

• Adding new API endpoints
• Adding new optional request parameters
• Adding new fields to API responses
• Changing error messages (but not error codes)
• Performance improvements
• Bug fixes that don't change the documented behavior

Migration Strategy

1. Review the changelog: Understand what's changed in the new version
2. Update your SDK: Make sure you're using an SDK version that supports the new API version
3. Test in development: Update your code and test thoroughly in a non-production environment
4. Gradually roll out changes: Consider using feature flags to gradually migrate your code
5. Monitor error rates: After deployment, watch for any increase in API errors

Example Migration Guide: v2022-11-15 to v2023-04-30

// Change 1: Patient object structure changes
// Before (v2022-11-15)
{
  "id": "pat_1a2b3c4d5e6f",
  "name": "John Doe",
  "dob": "1980-01-15",
  "gender": "male",  // Deprecated field
  "contact": {
    "email": "john.doe@example.com",
    "phone": "+1-555-123-4567"
  }
}

// After (v2023-04-30)
{
  "id": "pat_1a2b3c4d5e6f",
  "name": "John Doe",
  "dob": "1980-01-15",
  "sex": "male",     // Renamed from "gender"
  "gender_identity": "male", // New field
  "contact_info": {  // Renamed from "contact"
    "email": "john.doe@example.com",
    "phone": "+1-555-123-4567",
    "preferred_method": "email" // New field
  }
}

To migrate your code:

// Before (using v2022-11-15)
function getPatientGender(patient) {
  return patient.gender;
}

function getPatientContact(patient) {
  return patient.contact;
}

// After (using v2023-04-30)
function getPatientGender(patient) {
  // Handle both versions
  return patient.sex || patient.gender || 'unknown';
}

function getPatientContact(patient) {
  // Handle both versions
  return patient.contact_info || patient.contact || {};
}

v2023-10-15 (Current)

v2023-04-30

v2022-11-15 (Deprecated)