This article describes how we manage changes to the Feedback Aide JavaScript API and associated backend REST services.

Our approach is designed to ensure a stable and predictable integration while enabling continuous improvement and worry-free delivery of new functionality.

How we communicate changes

Unlike Learnosity Build APIs, Feedback Aide doesn't use a Long Term Support (LTS) release system due to its fast-moving nature. We number our releases using a major.minor.patch format:

• Major increments signal significant product evolution — a meaningful shift in capabilities or architecture that may require integration changes.
• Minor increments introduce new backward-compatible functionality. 
• Patch increments deliver backward-compatible fixes.

Changes are communicated through release logs and documentation updates.

Backward compatibility

Feedback Aide is designed to preserve backward compatibility wherever possible. We distinguish between two types of changes: interface changes and behavioral evolution.

Interface stability

The API interface — endpoints, request parameters, response formats, methods, and error structures — is kept stable across releases. The following types of additive changes maintain compatibility with current integrations:

• New functionality
  • Introduction of API endpoints.
  • Additional public methods.
  • Optional request parameters.
• Response evolution
  • Addition of new JSON properties.
  • Inclusion of additional items in collections or arrays.
• Enum expansion
  • Introduction of new values to existing enumerations or type fields.
• Non-functional updates
  • Reordering of response properties.
  • Updates to human-readable error messages while preserving error codes and structure.

Behavioral evolution

Feedback Aide is built on evolving technologies, including large language models (LLMs) and external services, whose underlying behavior improves over time. While the API interface remains stable, outcomes such as feedback quality, evaluation depth, and content generation may evolve as the product improves.

This is by design and allows customers to benefit from continuous improvement in the quality and capabilities of the service without needing to change their integration code.

Occasionally, changes to underlying models or third-party services may be outside our direct control, such as when a model provider discontinues a version. In these cases, we work to maintain comparable or improved performance, but outputs may vary during transitions. We monitor for regressions and iterate to restore or exceed prior quality levels.

How we handle breaking changes

When a breaking change to the API interface is necessary, our approach depends on the scope and impact of the change. In every case, however, our goal will always be to handle these changes as efficiently as possible and give our customers the opportunity to adjust.

Whenever possible, our aim is to:

• Provide advance notice to our customers via documentation.
• Publish migration guidance through documentation and release logs when changes are introduced.
• Provide targeted outreach if integrations will be impacted by major releases

The efforts will be determined case-by-case, based on:

• Minor-scope changes (for example, tightening a validation rule or making a field required): We will introduce transitional support — such as accepting both old and new formats, or applying conditional rules — and plan a cutover period to give customers time to adapt.
• Substantial changes representing significant product evolution: We will introduce updated interfaces alongside existing ones, allowing customers to migrate on a coordinated timeline. Existing interfaces remain operational during the transition period, and we provide documentation-based migration guidance before prior interfaces are retired.

Integrator best practices

To ensure resilience as APIs evolve, integrators should design for forward compatibility.

Recommended practices:

• Avoid strict schema validation that rejects unknown fields.
• Gracefully handle additional or unexpected response properties.
• Implement tolerant parsing for enum values, such as default or fallback handling.
• Do not rely on property ordering in JSON responses.

This approach ensures integrations remain stable as new functionality is introduced.

Feature lifecycle and removal

When a feature is scheduled for removal or replacement:

• It is marked as deprecated in documentation and release logs.
• During deprecation, the feature remains functional but receives no active development beyond critical security fixes.
• We notify broadly and publish migration guidance to the recommended alternative.
• Removal only occurs after a clear migration path and time to adjust have been provided.

Customers are never left without a path forward as we ensure alternatives are available and provide support throughout the transition.