Skip to main content
All CollectionsDevelopers
API upgrades
API upgrades

Keep track of changes and upgrades to the Finazon API

George Huxley avatar
Written by George Huxley
Updated over a year ago

Your API version determines the behavior of the REST API and WebSocket, influencing the properties visible in responses, the parameters allowed in requests, and other aspects. You can choose to set your version to the latest or to a specific one. When a breaking change occurs in the API, a new dated version is released. To prevent disruptions to your code, consider adhering to a particular version.

Backward-compatible changes

Finazon considers the following changes to be backward-compatible:

  • Adding new API resources.

  • Adding new optional request parameters to existing API methods.

  • Adding new properties to existing API responses.

  • Changing the order of properties in existing API responses.

  • Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.

    You can safely assume object IDs we generate will never exceed 255 characters, but you should be able to handle IDs of up to that length. For example, if you're using MySQL, store IDs in a VARCHAR(255) COLLATE utf8_bin column (the COLLATE configuration ensures case-sensitivity in lookups).

  • Adding new event types.

    Your WebSocket listener should gracefully handle unfamiliar event types.

Upgrading your API version

If you're running an older version of the API, upgrade to the latest version to benefit from new functionality and streamlined responses, making the API faster for you. Upgrading your API version will affect:

  • The API calls you make without specifying a version in the URL: the parameters you can send and the structure of objects returned.

  • The structure of objects received with endpoints such as time series.

  • The structure of objects sent to your WebSocket endpoints. If an endpoint has an explicit version set, it will remain unaffected.

To see what version you're running, visit your Dashboard or check the response header. To upgrade to the latest version, specify the version in the URL.

When performing an API upgrade, ensure you specify the API version you're integrating against in your code.

Rolling back your API version

After you've upgraded your API version, you can safely roll back to the previous version by specifying it. However, note that over time, we may discontinue support for older versions.

Stay informed

We share information on new additions and changes to Finazon's API and language libraries in the Finazon Community on Discord. Be sure to join the developer channel to stay informed.

Did this answer your question?