API Versioning

​

API Versioning

​

Current Version

https://api.smartbills.io/v1/expenses

​

Version Format

https://api.smartbills.io/{version}/{resource}

• https://api.smartbills.io/v1/receipts
• https://api.smartbills.io/v1/expenses
• https://api.smartbills.io/v1/customers

​

Backward Compatibility

• Adding new API endpoints
• Adding new optional request parameters
• Adding new properties to API responses
• Adding new webhook event types
• Adding new error codes

• Removing or renaming API endpoints
• Removing or renaming request parameters
• Removing or renaming response properties
• Changing the type of existing fields
• Changing authentication methods
• Changing error response formats

​

Version Lifecycle

​

Active Support

• New features and enhancements
• Bug fixes and security updates
• Full technical support

​

Deprecation Notice

1. We provide at least 12 months notice before deprecating the old version
2. The old version continues to work during the deprecation period
3. You receive notifications about the upcoming deprecation
4. Migration guides are provided

​

End of Life

• The old version stops receiving updates
• API requests may return errors
• You must upgrade to the new version

​

Checking Your API Version

const response = await fetch('https://api.smartbills.io/v1/expenses', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

// Response headers include version information
console.log(response.headers.get('X-API-Version')); // "v1"

response = requests.get(
    'https://api.smartbills.io/v1/expenses',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)

# Response headers include version information
print(response.headers.get('X-API-Version'))  # "v1"

var response = await client.GetAsync("https://api.smartbills.io/v1/expenses");

// Response headers include version information
var version = response.Headers.GetValues("X-API-Version").FirstOrDefault();
Console.WriteLine(version);  // "v1"

​

Migration Between Versions

1. Review the Changelog
   • Read the migration guide for the new version
   • Understand what has changed
2. Test in Pre-Production
   • Update your code to use the new version
   • Test thoroughly in the pre-production environment
3. Update Your Code
   • Make necessary changes to handle new response formats
   • Update error handling if needed
4. Deploy to Production
   • Deploy your updated code
   • Monitor for any issues

​

Best Practices

// Good
fetch('https://api.smartbills.io/v1/expenses')

// Avoid
fetch('https://api.smartbills.io/expenses')

// Good: Only use fields you need
const { id, amount, merchant } = expense;

// Avoid: Strict validation that breaks with new fields
if (Object.keys(expense).length !== 10) {
  throw new Error('Unexpected response format');
}

​

Version History

​

v1 (Current)

• Complete REST API for receipts, expenses, and customers
• OAuth2 authentication
• Webhook support
• Comprehensive error handling
• Multi-language support

​

Getting Help

• Email: [email protected]
• Developer Portal: https://developers.smartbills.io
• Documentation: https://docs.smartbills.io