Climatiq implements two versioning systems: Data Versioning and API Versioning. Data Versioning ensures stability in underlying data, crucial for those using
data namespace features or providing selector overrides. On this page, however, we focus on API Versioning, which deals with the parameters the API accepts and returns, and how these may change over time.
We'll explore feature groups and the two types of endpoints in the Climatiq API: General Availability (GA) and Preview.
Endpoints are categorized into feature groups, sharing a URL namespace. For instance, endpoints under
/data/ belong to the
data feature groups, respectively.
Each feature group has a version in the URL, like
v2-preview1, making a complete URL look like
compute/v1/metadata. Feature groups (and their endpoints) are divided into two variants based on their versioning:
- General Availability (GA) feature groups have versions, such as
- Preview feature groups have versions with a preview designation, such as
Endpoints under a General Availability (GA) feature group are stable, production-ready, and maintain backward compatibility. They do not introduce breaking changes. When a new GA version is released, the previous version enters a deprecation phase outlined as follows:
- Announcement: We announce the new version, and the deprecation of the old version. This is done in the monthly release notes.
- One-Year Timeline: The deprecated versions remains active for minimum one year post-announcement.
- Regular Communication: Through release notes, we will keep you updated on any endpoints nearing their deprecation date.
- Direct Outreach: When we are nearing the one-year mark, we will perform direct outreach to users still using any endpoints as a final reminder before the retirement.
- Final Removal: The old endpoints are officially removed after the deprecation period.
While endpoints that are GA avoid breaking changes, they can still evolve in a variety of ways:
- Addition of new optional parameters.
- Returning new fields in the response.
- Methodological adjustments, like routing changes or updated emission factors.
This means that while your original code will continue to function, the exact results may vary over time. If consistency is important to you, you should consider storing the responses locally.
Endpoints under a Preview feature group are for developers who want the newest Climatiq has to offer, even if it comes at having to adapt faster to changes. New endpoints, or new versions of existing endpoints initially appear in preview, undergoing one or more iterations before becoming a GA version.
Preview endpoints have a much shorter deprecation cycle. For this reason, accessing preview endpoints require you to contact Climatiq for access, so you can confirm you're ready to update frequently.
The deprecation process for preview endpoints is as follows:
- Immediate Notice: Users are informed directly about deprecation as soon as a new version is released.
- One-Month Notice Period: There's typically a one-month window before endpoint removal.
- Endpoint Deletion: The older preview version is removed after a month.
Let's explore a hypothetical scenario to illustrate this process. In this scenario, Climatiq offers an endpoint for calculating the carbon emissions of various fruits, accessible at
fruits endpoint falls under the feature group
food and is part of
Climatiq decides to modify this endpoint in a way that breaks backward compatibility - for instance, realizing the need to include fruit type for more precise calculations.
Consequently, a new
preview endpoint is introduced at
https://preview.api.climatiq.io/food/v2-preview1/fruits. This represents the first preview of what will eventually become the General Availability (GA) version 2.
Subsequently, it becomes clear that the endpoint also requires the country of origin for each fruit as a mandatory parameter. In response, a second preview endpoint is launched at
https://preview.api.climatiq.io/food/v2-preview2/fruits, denoting preview version 2, of what will still eventually become GA v2.
Following this release, users of
preview1 will be directly informed, with a one-month period provided for transitioning to
After thorough research and consideration, with no further changes anticipated for
v2-preview2, the endpoint is advanced to its
GA phase. This entails:
- The introduction of a new URL at
- Outreach to users of the
preview2endpoint, offering a one-month window to migrate to the GA version.
- Announcement in our release notes that "Food v2" has been officially released, and that "Food v1" will remain operational for one more year.
- Direct communication with users of "Food v1" as the end of its availability approaches.
- One year after the release of "Food v2", deprecation of "Food v1".
The example provided earlier focused on a single endpoint within the
food feature group. However, it's common for feature groups to contain multiple endpoints. For instance, in our hypothetical scenario, the
food feature group could also include a
It's important to note that when any endpoint within a feature group undergoes changes, all endpoints in that group are released as a new version. So, even if only the
/fruits endpoint changes, there would also be a new version for the
/vegetables endpoint, resulting in
food/v2/vegetables. This new version would be identical to
food/v1/vegetables in all aspects except for its URL.
The rationale for versioning all endpoints within a feature group together is to ensure compatibility and seamless integration. Often, you might need to use data from one endpoint as input for another within the same group. By maintaining consistent versioning across the group, we ensure that all endpoints within a version are designed to work together.