Introducing API Versioning: A Strategic Upgrade for Enhanced Stability and Control for API Integrations

We’re thrilled to announce a significant enhancement to our API infrastructure: the introduction of API versioning, which is vital for maintaining seamless communication and data exchange between applications during software development. The introduction of API versioning is a strategic change to empower our customers with greater control, better stability, and smoother integration processes.

Why API versioning matters

APIs serve as the backbone of modern software ecosystems, enabling diverse applications to interact with each other and share data seamlessly. However, as platforms evolve, managing changes without disrupting existing systems becomes a challenge.

API versioning is our strategic response to this challenge, offering substantial benefits:

• Backward compatibility where existing integrations will continue to operate without any interruptions, ensuring operational continuity.
• Clear updates on new features and improvements are introduced in a controlled, transparent, and predictable way.
• Choice and flexibility to choose which API version best fits the customer’s operational needs and compatibility requirements.

How API versioning works

The implementation of API versioning marks a pivotal shift in how our APIs will be managed moving forward:

• Versioned endpoints: Each API endpoint is now tied to a specific version, clearly designated in the URL enabling control of which API version a customer is interacting with.
• Enhanced documentation: To bring clarity and support, our revamped API documentation now includes comprehensive details about each version, enabling easy navigation through changes and updates.
• Deprecation policy: To facilitate a smooth transition to newer versions, we provide explicit guidelines on deprecated features and the timelines for migration.

Refining our approach: Key changes to the Qualys API management and release strategy

Our current strategy includes a 30-day advance notification for breaking changes and a 15-day notification for non-breaking updates. However, we recognize the challenges our customers face in adapting rapidly to any significant API changes in their client programs within a limited 30-day period. As we continue to innovate, we are refining these processes to better suit the needs of our users in this digital automation age of increased API adoption.

To optimize our API infrastructure and address the challenges faced by our users, we’re implementing several strategic changes to our API management and release protocols. These changes are designed to enhance predictability, transparency, and ease of integration, ensuring that our APIs remain robust and adaptable to your evolving needs.

Strategic Enhancements to API Management

• First-class software artefacts – Recognizing the importance of APIs, we now treat all APIs as first-class software artefacts. Each API endpoint will have a version number reference for better API management and clarity. For example, the API endpoint /api/2.0/fo/scan indicates version 2.0, while /api/3.0/fo/scan/compliance denotes version 3.0.
• Version incrementation – Any change made to an API will result in an incrementation of its version number. Breaking changes, which alter the API in significant ways, will increment the major version number. For instance, a major update from /api/2.0/fo/scan to /api/3.0/fo/scan will be distinctly visible in the URL of the API.
• Explicit adoption of new changes – Customers wishing to utilize the latest updates must explicitly use the new API endpoint URL in their client programs to ensure that the upgrades are deliberate and beneficial to specific use cases.
• Continued support and deprecation policy – Previous versions of the API, such as /api/2.0/fo/scan, will continue to be supported for six months following the release of a newer version. Both versions will be documented comprehensively during this period. At the end of six months, the older version will be deprecated, with clear notices published in our API documentation, indicating the discontinuation date.

• Handling non-breaking changes – Changes that do not disrupt existing functionalities—termed non-breaking changes—will increase the minor version number and will not be visible in the API’s URL. Such changes allow customers to continue using their current setups without any modifications, while automatically benefiting from the updated functionalities.
• Documentation and revision history – Our API documentation will be updated to reflect all changes, whether breaking or non-breaking. A detailed revision history section will document the evolution of each API, providing a transparent trail of updates and enhancements.

These planned changes help deliver a superior, reliable, and adaptable API ecosystem. By ensuring that each API is treated as a critical component of our infrastructure, we are setting new standards in API management that empower our customers to build, innovate, and scale with confidence.

Defining breaking changes in new API management

It is crucial to precisely define what constitutes a breaking change within our API ecosystem to ensure clarity.

A breaking change is any alteration that potentially disrupts existing client implementations, requiring updates to client programs to maintain functionality.

Understanding these changes is key to managing API versions effectively and aligning with best practices for software development.

Criteria for Identifying Breaking Changes

Breaking changes include modifications that affect the structure, behavior, or contractual obligations of an API. These changes are classified as follows:

• Introduction of required parameters – Adding new “required” input parameters to an existing API can break existing client integrations that are not designed to include these new mandatory fields.
• Validation changes – Alterations to the validation rules for existing parameters that may render previous inputs invalid or incompatible.
• Data type modifications – Changes to the data types of existing parameters which could affect data serialization and parsing, leading to integration failures.
• Request/response format changes – Modifications to the format of API requests or responses, such as changing from XML to JSON, necessitate updates in client handling of these data formats.
• HTTP verb changes – Changing the HTTP method (e.g., from POST to GET) for an API endpoint alters how requests should be formed and handled, impacting the semantic meaning of the operation.
• Error code revisions – Modifications to response codes or error codes that can change the interpretation of responses and error handling routines.
• XML schema changes – In APIs using XML, changes to the XSD/DTD specifications such as renaming elements, reordering elements, adding new elements (optional or mandatory), or removing elements, will require client-side adjustments.
• JSON structure changes – For JSON-based APIs, changes that impact the structure, such as renaming elements, reordering elements, adding new mandatory elements, or removing elements, necessitate updates to client programs.
• CSV output adjustments – In APIs returning CSV formatted data, changes such as modifying column names, inserting new columns between existing ones, or altering separators/delimiters will impact how client programs parse and handle CSV data.

Defining non-breaking changes in new API management

Non-breaking changes are adjustments to APIs that do not disrupt existing client integrations or require modifications to existing client programs to continue functioning as expected.

These types of changes allow for enhancements and extensions to APIs without imposing the need for immediate action by end-users. Understanding and categorizing such changes are vital for continuous improvement while ensuring stability.

Criteria for Identifying Non-Breaking Changes

The essence of non-breaking changes lies in their non-disruptive nature. These changes are designed to add functionality or information that clients can use optionally, without affecting the existing behavior or outputs of the API. Here are specific instances that represent non-breaking changes:

• Addition of optional parameters – Introducing new “optional” input parameters or search filters to an existing API does not affect existing client programs. The input parameters are used at the discretion of the user, providing additional flexibility and functionality without altering the baseline behavior of the API.
• JSON enhancements – For APIs that utilize JSON for inputs or outputs, the addition of new optional elements is a typical example of a non-breaking change. The optional elements do not require existing client programs to alter their codebase, as these new elements do not mandate changes in API consumption or data handling:
  • New optional elements – Integrating new optional elements into JSON structures allows developers to enhance functionality and provide more data without disrupting existing integrations. Clients can choose to ignore these additions or leverage them to gain additional insights and capabilities.

Universal adoption of the new API management approach

Focusing on delivering solutions that are innovative, reliable, and user-centric, all Qualys products will adopt the newly refined API management strategy over the next six months, bringing a significant enhancement to our service delivery and operational agility for both Qualys as well as our valued customers.

Benefits of the new approach

• Extended testing window – Under the new strategy, customers will benefit from a more extended time window than the current 30-day period to experiment with new APIs, allowing for thorough testing and integration, ensuring that new functionalities can be seamlessly incorporated into your existing systems.
• Dual API access – To facilitate a smooth transition and minimize disruptions, customers will have access to both the new and old versions of an API concurrently for conducting comprehensive tests against the new API while maintaining the production environment with the old API. This reduces the risk of integration issues and ensures that customers can confidently and systematically adopt new features.
• Enhanced agility for Qualys – This new strategy empowers Qualys with increased agility in API releases. By streamlining the versioning process and providing clear frameworks for updates and deprecations, we can rapidly adapt to changing technological landscapes and customer needs.

As we continue to refine and advance our API management strategies at Qualys, we encourage you to review the new API versioning guidelines and start integrating these practices into your development processes. Take advantage of the extended testing windows, the dual API access for seamless transitions, and the continuous support provided through our detailed documentation. Explore the new features and provide your feedback.

For further information, detailed guidance, or to start testing the new API versions, please visit our documentation page.

We understand you may have questions or require further clarification on how these changes could impact your existing systems. Our Support team is fully prepared to provide you with the personalized support necessary for a smooth transition. Connect with us here.