Backward compatibility

This document outlines our approach to maintaining backward compatibility for our API. Our goal is to ensure a stable and reliable experience for developers while evolving our API to meet future needs.

Key Principles

1. Avoiding Breaking Changes: We prioritize maintaining existing functionality to ensure existing integrations continue to work without requiring changes.
2. Non-removal of Data: Any enrichment of JSON responses will be additive; we will not remove data fields from responses.
3. Versioning of Endpoints: Introduction of new endpoint versions (e.g., v2, v3, v4) will be done to evolve the API. Previous versions will be deprecated but remain operational for a period.
4. Deprecation Notice: Developers will receive at least 6 months' notice before we cease support for a deprecated endpoint version.

Versioning Strategy

Introducing New Versions

• New versions of an endpoint will be introduced as v2, v3, etc.
• These versions may introduce new functionality or modify existing behavior.

Simultaneous Operation

• Two versions of one endpoint can operate simultaneously.
• This allows developers to transition to the newer version at their convenience.

Deprecation Process

1. Announcement: When a version is deprecated, an announcement will be made via official channels.
2. Transition Period: The deprecated version will remain operational for at least 6 months post-announcement.
3. Support: During the transition period, support will be provided for both the deprecated and new versions.
4. Cease of Support: Post the transition period, the deprecated version will no longer be supported or operational.

Guidelines for Developers

1. Stay Informed: Subscribe to our developer newsletter and announcement channels to stay informed about new versions and deprecations.
2. Plan for Migration: Once a deprecation notice is received, plan and execute the migration to the newer version within the 6-month period.
3. Test New Versions: Thoroughly test your integration with the new version before migrating to ensure a seamless transition.
4. Feedback Loop: Provide feedback on new versions or any challenges faced during migration. This helps us to improve the API.

Best Practices

1. Regularly review the API documentation for updates.
2. Design your integration to be flexible to accommodate new fields in JSON responses.
3. Monitor API deprecation announcements and proactively plan for migrations.

API Breaking Changes Definition

This document explains what AMPECO considers a breaking change in the Public API and how we handle them.

What is a Breaking Change?

A breaking change is any modification to the API that could require your integration to be updated to continue working correctly. This includes changes that would cause existing API calls to fail, return unexpected results, or behave differently than before.

We have strict policies about when we allow breaking changes. For most established features, we use non-breaking alternatives like deprecation and versioning instead of making immediate breaking changes.

Breaking Changes (Requires Integration Updates)

Response Changes

• Removing a response property
• Removing an enum value from a field
• Changing the data type of a response field (e.g., string to object)
• Adding a required property to a response object
• Making a previously optional response property required
• Changing the structure of a nested response object
• Removing an HTTP status code that was previously returned
• Changing the meaning or behavior of a response field

Request Parameter Changes

• Adding a new required parameter (request body, query, or path)
• Removing an existing parameter
• Changing the data type of a parameter
• Removing support for a previously accepted enum value
• Adding validation constraints that reject previously valid requests
• Changing how parameters are processed or interpreted

Endpoint Changes

• Removing an API endpoint entirely
• Removing support for an HTTP method (e.g., removing DELETE when only GET and DELETE were supported)
• Changing the request path or URL structure
• Removing or changing URL query parameters
• Removing a response status code

Authentication and Authorization Changes

• Adding new required authentication mechanisms
• Removing support for a previously accepted authentication method
• Changing permission requirements for an endpoint
• Requiring additional scopes that were not previously required

Non-Breaking Changes (No Integration Updates Required)

Adding New Response Content

• Adding a new optional response property
• Adding a new enum value to a field
• Adding a new HTTP status code that can be returned
• Expanding a response object with additional fields
• Adding new nested objects to responses

Making Request Parameters More Flexible

• Adding a new optional parameter
• Making a previously required parameter optional
• Adding a new enum value that a parameter accepts
• Relaxing validation constraints (e.g., increasing a character limit)

Adding New Endpoints

• Creating a new API endpoint
• Adding a new HTTP method to an existing endpoint (when methods were mutually exclusive)

Documentation Changes

• Updating endpoint descriptions or documentation
• Clarifying expected behavior without changing actual behavior

How We Handle Breaking Changes

We avoid breaking changes whenever possible by using non-breaking alternatives. Breaking changes are only made in specific circumstances:

When Breaking Changes Are Allowed

• Newly released features - Features that are brand new and have been released recently where no integrations are yet using them
• Niche features with limited adoption - Features used by only a couple of clients where we have communicated in advance that breaking changes may occur

How We Deprecate Instead of Breaking

For established features with active integrations, we use a deprecation approach instead of making immediate breaking changes:

• Deprecate the old property or endpoint - We mark properties or endpoints as deprecated
• Introduce new versions - We create new versions of endpoints or properties alongside the old ones
• Maintain compatibility - Both versions continue to work so your integration does not break

When Removing Deprecated Features

Before we remove a deprecated endpoint or property, we provide advance notice:

• We send you notification ahead of time about the removal
• We specify the timeline for the removal
• You have time to migrate to the new endpoint or property
• Only after this notice period do we remove the deprecated feature

Best Practices for Your Integration

Handle Response Changes

• Ignore unknown fields - Your code should not fail if response objects contain fields you do not recognize. New fields may be added without breaking your integration.
• Handle new nested objects gracefully - If we add new objects within existing responses, your code should continue to work without modification

Handle Enum Values

• Do not validate against a hardcoded list of enum values - Your code should accept any string value for enum fields, not just the ones currently documented
• Use a default fallback for unknown enum values - If you need to handle specific enum values, implement a default case for values you do not recognize rather than failing
• Expect new enum values - We may add new enum values to fields at any time without notice, and your integration should handle them gracefully

Monitor Changes

• Handle nullable values - Check for null values even if fields were not previously nullable
• Monitor release notes - Review our release notes when updating to new API versions to understand what has changed
• Test after updates - Verify your integration works after updating to a new API version
• Subscribe to deprecation notices - Stay informed about deprecated endpoints and properties so you can plan migrations

Questions?

For questions about API compatibility or to discuss how changes may affect your integration, please contact our API support team.