Global Data
Browse guides
View as Markdown

API Versioning

Overview

Versioning is a critical aspect of API design, ensuring that changes to the API can be rolled out without negatively impacting existing applications. The Global Data API employs a straightforward versioning approach by incorporating the version number in the request URL. This section provides an understanding of the versioning scheme and how changes are managed.

Version Number in URL

The version number is embedded directly in the API endpoint URL. For instance:

https://gdapi.globaldata.net.au/api/v2/resource-endpoint

In the above example, v2 indicates that the API endpoint belongs to version 2.

Changes & Backward Compatibility

  1. Additions: New resources and methods can be introduced to an existing version without changing the version number, provided they don't affect backward compatibility. This ensures seamless integration for developers relying on the current version.

  2. Modifications: If a method undergoes changes that alter its functionality in a way that disrupts backward compatibility, a new version of the API will be introduced.

This documentation pertains to version 2. Ensure to check the version in the endpoint URL to guarantee you're accessing the correct version.

Version Support Lifecycle

Every version of the Global Data API receives full support for a minimum of 12 months from the introduction of its subsequent version. This provides ample time for developers to adapt to newer versions without abrupt disruptions.

For example, when version 3 is launched, version 2 will continue to be supported for at least another 12 months.

Transitioning Between Versions

It's advisable for developers to:

  1. Regularly check for announcements on new API versions.
  2. Test their applications against the new version during the support overlap period.
  3. Migrate to the newer version before the end of the previous version's support period.

Best Practices

  • Stay Updated: Monitor official channels for announcements related to version releases or changes.

  • Maintain Flexibility: Design your application to be adaptable, making it easier to accommodate changes in the API.

By adhering to these guidelines and understanding the versioning strategy, developers can ensure smooth interactions with the Global Data API and easily navigate between versions.

Previous Rate Limiting Next Data Retention and Footprints