GraphQL Versioning
At CloudSoda, the company strives to continuously improve and evolve its GraphQL API to provide enhanced functionality and better experiences to its users. As part of this process, CloudSoda’s GraphQL schema undergoes updates and refinements over time. This page aims to guide users through the versioning of CloudSoda’s schema and how to manage these changes effectively.
Schema Evolution
The GraphQL API schema at CloudSoda is unversioned , meaning it evolves organically without distinct version numbers. CloudSoda commits to maintaining backward compatibility for the majority of changes. However, some enhancements might not be backward compatible, and these will be clearly communicated well in advance.
Backward Compatibility
It’s crucial for client applications to understand the evolving nature of CloudSoda’s GraphQL schema. To ensure smooth operation, users are encouraged to follow these best practices:
- Avoid Over-fetching Data: Retrieve only the necessary data for your application to minimize the impact of schema changes on queries. Utilize GraphQL’s flexibility to request only the required fields, as fetching unnecessary data could become obsolete due to future schema updates.
- Be Prepared for Schema Changes: Expect additions to existing objects, expansions of enums, or the introduction of new fields. Plan your application to handle such changes gracefully.
- Stay Updated and Proactive: Regularly check CloudSoda’s documentation and announcements for any upcoming changes or deprecations. Staying informed is essential to adjust applications accordingly.
Breaking Changes
In rare cases where a change affects backward compatibility, CloudSoda will provide comprehensive documentation and advance notice. Such changes might involve:
- Removal of Fields or Types: Fields or types might be deprecated and eventually removed. CloudSoda will communicate such changes well in advance and provide alternative solutions.
- Enum Expansion or Modifications: Enumerations might evolve, potentially affecting the current behavior of your application. Preparing for these changes in advance is essential.
Updates & Announcements
CloudSoda prioritizes transparent communication about upcoming changes to its GraphQL schema. Announcements will be made through various channels, including:
- Changelog Updates: Clear and concise information about modifications, deprecations, or additions.
- API Documentation Updates: CloudSoda’s API documentation will always reflect the latest changes and enhancements.
- Email Release Notes: For enterprise customers, any upgrades to customer deployments include a summary of all the improvements. Announcements about schema evolution will be communicated through this channel.