API Versioning
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.
Feature Groups and Versions
Endpoints are categorized into feature groups, sharing a URL namespace. For instance, endpoints under /compute/ or /data/ belong to the compute or data feature groups, respectively.
Each feature group has a version in the URL, like v1 or 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
v1orv2. - Preview feature groups have versions with a preview designation, such as
v1-preview1,v2-preview1orv2-preview2.
General Availability (GA) Endpoints
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.
Preview Endpoints
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.
Example
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 https://api.climatiq.io/food/v1/fruits.
This fruits endpoint falls under the feature group food and is part of version 1.
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 preview2.
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
https://api.climatiq.io/food/v2/fruits. - 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 /vegetables endpoint.
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.