Changes in our Public API: Transitioning to Date-Based Versioning

We're excited to announce a significant change in how we version our Public API at Nuvemshop. Starting in March 2025, we'll be transitioning from our current fixed versioning system (v1) to a date-based versioning format (YYYY-MM).

This change represents a major step forward in our API lifecycle management, providing better clarity around when features are introduced and making it easier for developers to track API evolution over time. The new versioning system will help both our team and our developer community better understand and manage API changes.

Key highlights of this transition:

• Moving from fixed version numbers (v1) to date-based versions (e.g., 2025-03)
• Introduction of an unstable version for testing new features
• More frequent and predictable release cycles
• Improved transparency in feature rollouts

Where we are - Fixed versioning (As in v1 version)

Managing an API lifecycle involves careful planning, deployment, and maintenance to ensure backward compatibility, seamless client experiences, and adaptability to evolving requirements. At the core of this process lies the API versioning strategy.

For a long time now, at Nuvemshop our public API was versioned using a fixed version schema, with v1 version being the only published stable version. Fixed versioning assigns a static number to a specific iteration of an API, with clear advantages that made it a reliable initial choice for us. Simplicity was the main advantage: It is easy to understand and communicate. And if we wanted to grow, we simply replaced the major number with another, to clearly distinguish major changes.

However, different reasons took us on a different path: all the resources added or modified in the last few years were put into one version (v1) making it difficult to understand when a change was introduced. We have no track as to when we modified the behavior of an endpoint or added new functionality, we’ve only tracked (publicly) changes on the documentation site (See Changelog)

This format worked for us for years. We have been using the v1 versioning schema for a long time, more than 10 years. Now, we are facing its limitations:

1. Lack of Context: v1 provides no insight into the timeline of changes.
2. Rigid Updates: It is challenging to communicate interim improvements if we just use the same major version.

Today, Nuvemshop has evolved significantly, introducing many new features and capabilities. We believe it is time to adopt a more robust API versioning scheme and establish a comprehensive process for managing API and feature updates—a complete API lifecycle definition.

Transitioning to Date-Based Versioning (e.g., YYYY-MM)

Date-based versioning uses the year and month (e.g., 2025-01) to define the version. This approach provides temporal context and allows for more frequent updates without the constraints of fixed numbering.

Key Features:

• Format: YYYY-MM, where YYYY represents the year, and MM represents the month.
• Granularity: Allows finer granularity for updates and improvements.

Example:

• 2025-01: January 2025 version.
• 2025-06: June 2025 version, indicating updates since January.

Benefits of Date-Based Versioning

1. Clear Evolution Path: Users can easily determine when changes were introduced.
2. Encourages Incremental Updates: Simplifies rolling out frequent improvements.
3. Improved Planning: Aligns API versions with organizational release cycles.
4. Backward Compatibility Clarity: Clearly communicates the age and relevance of an API version.

Adding new features to Public API - Introducing unstable version

To ensure stability and maintain a reliable API for our users, we will introduce a new approach to feature management:

• Unstable Version: New features will be introduced in the unstable versions before they are officially released. This allows for testing and feedback before committing changes to stable versions.
• Stable Versions: A stable version is a release that has undergone sufficient testing and validation to be considered reliable for production use. It does not receive experimental changes and is only updated with bug fixes, security patches, and necessary maintenance updates. We will follow an annual plan for stable releases, coordinating with all teams, and ensuring that a thoroughly tested version is available at least once a year, allowing users to plan their updates accordingly.

‼️ IMPORTANT: We currently do not have a defined policy for sunsetting stable versions, but we will be working on establishing clear guidelines for this soon.

In summary, New features will be added to a public release of the API by first introducing them in an unstable version. These unstable versions allow for thorough testing and the gathering of user feedback. Once the feature has been sufficiently tested and refined based on the feedback, it can be included in a stable release. No new features will be introduced directly into the v1 stable release after the 2025-03 release.

Transition Plan

We are planning to start using this API format in 2025, adding a unstable version to test all changes generated between versions. We estimate having the first release of this format in march

Dual Support Phase:

• We will maintain both v1 and date-based versions temporarily.
• This will allow clients to test and migrate to the new format.

Documentation Updates:

• We're updating our API documentation to include examples and migration guides. We'll provide a specific changelog to summarize critical changes in the version.

Deprecation of Fixed Versions:

• Once we gather experience and feedback, we will gradually phase out fixed versions, providing clear timelines and support.

We expect to be working on this changes during Q1 2025.

Conclusion

To continue growing as a company, we’ll start transitioning our Public API to a date-based versioning strategy, and define an API lifecycle by promoting flexibility, clarity, and adaptability. While this approach requires initial effort to implement and communicate, it provides significant long-term benefits, including better alignment with development cycles and enhanced user experiences.

By carefully managing the transition, we can ensure a smooth migration and establish a robust foundation for future API evolution.