API Life cycle
Chargetrip uses a single, evolving GraphQL API endpoint. This way the latest features and improvements are always available without managing multiple API versions. While a single-endpoint approach simplifies integration, it also requires a clear strategy for managing changes. This page outlines Chargetrip’s approach to API evolution and provides guidelines for building integrations that remain stable as the API evolves.
Non-breaking changes
A non-breaking change is a modification that is safe and backward-compatible. Because these changes won’t disrupt existing integrations, they will be introduced without a formal announcement.
What this includes
- Adding a new query, mutation, or subscription.
- Adding a new optional input.
- Adding a new field to an output.
- Making a previously required input field optional.
- Adding a new value to an existing enum type.
enum types are not exhaustive. New values will be introduced to the existing enum types over time as new features are added. Always implement a catch-all case in the application’s logic to gracefully handle new enum values.
Breaking changes
A breaking change is a modification that could cause an existing integration to stop working. Because such changes can be disruptive, the introduction of any breaking change follows a formal deprecation process to give ample time to adapt.
What this includes
- Removing or renaming an existing query, mutation, or subscription.
- Removing or renaming an existing field.
- Removing a value from an existing enum type.
- Changing the type of a field.
- Making an optional input field required.
- Changing the core behavior of an existing field.
Deprecations
When an API functionality is deprecated, it continues to work normally for at least 12 months. After this notice period, the deprecated functionality is removed and requests using it will return GraphQL errors.
What this includes
- Deprecated fields marked with
@deprecatedin the GraphQL schema. - Deprecated fields flagged on the deprecations portal.
To prevent errors and service disruption, migrations must be completed before the scheduled removal date.
Beta / alpha features
Chargetrip uses an alpha and beta program to introduce and validate impactful new functionalities before they become part of the stable API. Unlike changes to stable features, any changes to alpha or beta features are exempt from the deprecation process. This means that fields or operations marked as alpha or beta may be changed or removed at any time without prior notice.
- For help understanding a deprecation or planning a migration, contact Chargetrip’s support team.
- For the latest API updates and announcements, visit release notes and deprecations.