Versioning and Changelog Overview

Versioning and change management are key to ensuring the Connect API remains robust, reliable, and easy to use. This section explains how we manage updates and communicate changes, with a focus on providing clarity and flexibility for our users.

How Versioning Works in Connect API

Our API Documentation consists of two layers:

1. Full OpenAPI Schema:
   The comprehensive schema covering the entire API, updated whenever any part of the API is changed.

2. Individual OpenAPI Product Files:
   Independent schemas for specific API products. These are updated only if there are changes within those specific products.

This structure ensures updates are granular and localized, simplifying integration for specific API products while maintaining the overall API version’s integrity.

API Description Versioning (info.version)

Each API product and the full schema include an info.version field in their OpenAPI description. This indicates the version of the API description, not necessarily the API version itself.

Purpose

The info.version field ensures transparency about changes to the API description. It may reflect updates to documentation, metadata, or descriptions, even if there are no changes to the actual functionality.

How It Works

When the API description changes—such as the addition of new endpoints, updated descriptions, or improved metadata—the info.version field is updated accordingly.

Example API Description Version (OpenAPI)

openapi: 3.1.0 # OpenAPI specification version
info:
  version: 1.12.4 # API description version

The info.version field is independent of the functional API version, but they may align for convenience. Keeping the description version updated ensures your integration uses the latest documentation and metadata.

When to Update the Description Version:

• Improved operation/parameter descriptions.
• Addition of new endpoints (non-breaking).
• Metadata updates (e.g., tags for improved documentation output).

Types of Changes

1. Non-Breaking Changes

Non-breaking changes enhance the API without disrupting current integrations. These changes allow for backward compatibility, ensuring seamless operation for existing users.

Examples of Non-Breaking Changes:

• New endpoints, parameters, or fields added to enrich functionality.
• Bug fixes or stability improvements that do not alter the API contract.

Best Practices for Handling Non-Breaking Changes:

• Flexible Integrations: Ensure your systems don’t rely on the order of returned data.
• Leverage Optional Fields: Adopt new features gradually by utilizing optional parameters and fields.

2. Breaking Changes

Breaking changes modify the API in ways that may disrupt existing integrations, such as removing or altering critical endpoints.

Examples of Breaking Changes:

• Removing/renaming an endpoint.
• Modifying parameter types, structures, or required status.

How We Manage Breaking Changes:

• Major Version Updates: These are clearly signaled with a major version increment (e.g., v1.x.x → v2.0.0).
• Advanced Notices: We communicate breaking changes well in advance to stakeholders, accompanied by migration guidance.

Change Log Strategy

We maintain a comprehensive changelog to document all changes, ensuring traceability and transparency.

Change Log Highlights:

• Updates are recorded for both the full OpenAPI schema and individual API product files.
• Changes are categorised by API product for easier navigation and isolation.
• Breaking and non-breaking changes are clearly labeled for clarity.

Tags

Each change in the changelog is tagged with a specific type to help you quickly understand the nature of the update:

• (Update): Indicates updates to existing parameters, features, or functionality.
• (Add): Highlights newly added parameters, endpoints, or features.
• (Fix): Represents bug fixes or corrections, such as schema adjustments.
• (Deprecation): Marks features or endpoints that are being deprecated and may be removed in the future.
• (Removal): Identifies features or endpoints that have been removed.

The changelog allows users to quickly identify updates relevant to their integration without needing to sift through unrelated changes.

Why This Matters

Our versioning and changelog approach prioritise clarity, stability, and ease of use. By maintaining granular updates at the product level and comprehensive changes at the schema level, we ensure:

• Minimal disruption to existing integrations.
• Clear communication of changes through the info.version field.
• A seamless process for adopting new features or transitioning to major updates.

Your trust in the Connect API is our priority, and this strategy helps us build reliable, predictable, and user-focused APIs.