Backward-Compatible API Updates

Bitso's commitment to maintaining non-breaking API enhancements ensures consistent API behavior, minimizing integration risk and supporting long-term stability for our users.

Bitso considers the following API changes to be backward-compatible:

• Adding new API endpoints: Introducing new endpoints that provide additional functionality is generally considered backward-compatible. Integrations that do not utilize the new endpoints remain unaffected.
• Adding new optional request parameters to existing API methods: Introducing new optional parameters to existing API calls does not break existing integrations. Integrations not providing the new parameters continue to function with the API's default behavior.
• Adding new properties to existing API responses: Introducing new data fields into the JSON responses of existing API calls is considered backward-compatible. Ensure your integration gracefully handles new, unexpected fields without errors.
• Changing the order of properties in existing API responses: While we aim for consistency, the order of fields within JSON responses might occasionally change. Integrations should rely on the field names rather than their order of appearance for data processing.
• Modifying the length or format of opaque strings: This includes changes to the length or format of identifiers (for example, order IDs, funding IDs, and withdrawal IDs), error messages, and any other human-readable string. The change might also involve adding or removing fixed prefixes. Ensure your integration can handle variations in the length and format of these strings. For example, use sufficiently sized string data types when storing Bitso-generated IDs in your database.
• Adding new event types to the WebSocket or Webhooks APIs: Introducing new event types in our WebSocket or Webhook APIs is considered backward-compatible. Ensure the listeners interacting with these APIs gracefully handle unfamiliar event types without disrupting their core functionality.

Important Considerations When Integrating

Keep the following key factors in mind to ensure a solid and seamless integration experience:

• Robust Data Handling: Design your integration to handle the addition of new API response fields without breaking. Avoid making assumptions about the presence or absence of specific fields beyond those explicitly required for your application's core functionality.
• Flexible String Handling: Be prepared to handle variations in the length and format of string-based identifiers and messages returned by Bitso APIs. Avoid imposing strict length limitations in your data models.
• Graceful WebSocket or Webhook Event Handling: If you use the Bitso WebSocket or Webhook APIs, ensure your client implementation can gracefully ignore or log unfamiliar event types without crashing or interrupting the processing of known event types.

By adhering to these guidelines, Bitso aims to evolve its APIs in a predictable manner, minimizing disruption to existing integrations. We will communicate any potentially breaking changes well in advance through our developer channels, giving you control and confidence in managing your integrations.