API Change Management Policy

Introduction

The API Change Management Policy describes how changes to APIs are controlled and managed within AppXite. This comprehensive guide outlines the systematic approach to collect, review, respond to, implement, communicate, and record change requests for all public APIs developed and managed by AppXite.

In this article:

• Definition and Scope
• API Maintenance and Versioning
• Documentation Requirements

Definition and Scope

Definition of Change: The creation of a new API(s) or any activity that changes the existing API structure, including, but not limited to, URL, headers, parameters, body, and payload.

In Scope: All public APIs are developed and managed by AppXite.

Not in Scope: 3rd party APIs. Examples: Microsoft Partner Center APIs.

API Maintenance and Versioning

Upon introducing changes to the APIs, such changes must be reflected according to the established version control framework. All API modifications follow a structured approach to ensure consistency and maintain partner integration stability.

Version Control Format

API version control uses the following standardized format:

• Major version releases: x.0 (Example: 2.0)
• Minor version releases: 0.x (Example: 0.3)

Versioning Principles

Major Version Releases

Major version releases shall apply to breaking changes, such as:

• Modifications of existing fields or API parameters that change current behavior: Changes to existing fields or parameters that remove data or options, change payload structure, or otherwise change the way things work making it backward incompatible
• Removal of fields or parameters: Some of the existing integrations will no longer operate in a new version

Minor Version Releases

Minor version releases shall apply to non-breaking changes, such as:

• New fields or parameters that are optional are being added to the API, but the existing fields and parameters are unchanged

Version Immutability

Backward Compatibility Requirements

Upon releasing the new major API version, the previous version shall be maintained for the period of 6 months following the new version release. After this period, the previous version will be deactivated. As a result, for 6 months both the previous and current versions will work as expected for the Partners that are using them.

Documentation Requirements

• Documentation availability: Documentations must be available for each version
• API Header requirement: Major version should be required parameter in API header when calling public APIs
• Example usage: Api-Version: v2

Summary

The API Change Management Policy ensures controlled, traceable, and partner-friendly API evolution through structured versioning, comprehensive documentation, and backward compatibility support. This systematic approach maintains integration integrity while enabling continuous API improvement and enhancement.

Related Content

• Navigating Platform APIs
• AppXite Platform API Access