Lifecycle

The API is built around a single, evolving GraphQL endpoint. This architecture ensures that new capabilities and performance improvements are delivered continuously without requiring migration between API versions.

This page outlines the different stability levels across the API, the stability guarantees of the stable API, the types of changes (breaking vs. non-breaking), and how deprecations are managed. For features currently in preview, see experimental features.

Feature lifecycle

Every feature sits at one of three stability levels: alpha, beta, or stable. Most features move through them in order, and stable features can only be retired through a deprecation process.

[ ALPHA ] ──> [ BETA ] ──> [ STABLE ] ──> [ DEPRECATED ] ──> [ REMOVED ] Opt-in        Enabled                      12+ month               by default                   notice window

Stable API

Stable functionalities represent the production-ready core of the API. Changes are classified into two categories, non-breaking and breaking.

Non-breaking changes

Backward-compatible additions that do not disrupt existing integrations. These are released continuously without advance notice or deprecation.

Non-breaking changes include:

• Adding a new query, mutation, or subscription.
• Adding a new optional input argument to an existing operation.
• Adding a new argument with a default that preserves existing behavior.
• Adding a new field to the output of an existing operation.
• Changing a required input argument to optional.
• Adding a new value to an existing enum type.

Building for non-breaking changes

Non-breaking changes can still affect clients that make rigid assumptions. To keep integrations resilient:

• Avoid strict object deserialization that fails when extra properties appear in payloads.
• GraphQL enum types are non-exhaustive and expand over time. Always implement a fallback default case in client logic.
• Inspect error extensions.exception.code values rather than matching against human-readable error strings.

Breaking changes and deprecations

A breaking change could break active existing integrations. As a consequence, any breaking change must first pass through a 12-month deprecation process.

Breaking changes include:

• Removing or renaming an existing query, mutation, subscription, field, or input argument.
• Removing or renaming enum values.
• Changing the data type of an existing field or input argument.
• Adding a new required input argument.
• Changing an optional input argument to required.
• Altering the business logic or behavior of an existing field.
• Changing an output field from non-nullable (!) to nullable.
• Changing the default value of an input argument or field.
• Changing pagination defaults, maximum page sizes, or documented sort order.

Deprecation timeline

When a breaking change requires removing or replacing a stable capability, it follows a strict three-phase timeline:

1. Deprecation announcementThe functionality is tagged with the @deprecated directive in the GraphQL schema. If applicable, a migration path is provided. The deprecation and respective removal date is announced simultaneously across three monitoring channels.
2. Active notice window (months 1–12)The deprecated functionality remains fully operational. If a migration path is provided, integrators should update their applications and adopt the new fields during this 12-month window.
3. Permanent removalAt the removal date, the functionality is permanently removed. Any subsequent requests using the functionality will fail schema validation with a GraphQL error.

Tracking Deprecations

Identify and track upcoming retirements across three channels:

• Inspect @deprecated(reason: "...") directives in your schema tooling.
• Review sunset dates and migration guides in the legacy section of the API or the deprecations portal.
• Monitor DEPRECATED_FEATURE warnings returned directly in API responses.

{  "data": {    "station": {      "id": "5e8c22366f9c5f23ab0eff39",      "amenityList": [        {          "name": "Coffee Shop",          "foursquareUrl": "https://foursquare.com/v/example"        }      ]    }  },  "extensions": {    "warnings": [      {        "code": "DEPRECATED_FEATURE",        "path": ["amenityList", "foursquareUrl"],        "message": "This feature is deprecated and will be removed. To prevent errors and service disruptions, migrate to the recommended alternative before the scheduled removal date. Visit https://developers.chargetrip.com/deprecations for more information."      }    ]  }}