API Breaking and Non-breaking Changes Guide

This guide helps you understand what constitutes a breaking and non-breaking change in our API responses and how to future-proof your integrations.

Our Commitment

For breaking changes, we will notify all clients at least 1 month prior to implementation. This gives you time to update your integrations before the changes take effect.

What We Consider Breaking Changes

These changes could break integrations and require updates to your code.

1. Removing or renaming fields

• Removing parameters (e.g., redness, puffiness, ita).

• Renaming keys (e.g., score → value, tag → label).

Impact: Code that accesses these fields by name will fail.

2. Changing data types

• Converting score: number to score: string.

• Converting grade: number to grade: object.

Impact: Strongly typed languages will fail at runtime or compile time.

3. Changing nullability

• Fields that were always present become optional or null.

Impact: Code that doesn't perform null checks may crash.

4. Restructuring nested objects

• Moving fields (e.g., parameters.redness.score → parameters.redness.metrics.score).

• Changing object nesting levels.

Impact: JSON path lookups and data bindings will break.

5. Changing field semantics

• Score scale changes (e.g., 0–100 → 0–1).

• Grade interpretation changes (e.g., 1 = best → 1 = worst).

Impact: Business logic and UI interpretations will be incorrect.

6. Removing supported variants

• Dropping specific views (e.g., left, right).

• Removing mask types (e.g., anonymised).

Impact: Integrations relying on specific data variants will fail.

7. Changing enum values

• Modifying enum formats (e.g., "very light" → "VeryLight").

• Adding unexpected enum values without documentation.

Impact: UI mappings to labels, icons, or colors will break.

8. Changing mask output format

• Switching mask format (e.g., png → svg).

Impact: Integrations expecting specific formats will fail to process responses.

What We Consider Non-Breaking Changes

These changes are safe and backward compatible. We may implement them without advance notice.

1. Adding new parameters

• New top-level parameters (e.g., hydration) can be safely ignored by existing clients.

2. Adding optional fields

• New fields added to existing objects are safe if existing fields remain unchanged.

3. Adding new mask formats

• Adding formats (e.g., webp alongside svg/png) while maintaining existing ones is safe.

4.Improving algorithm quality and precision

• Improvements to algorithm accuracy that result in slightly different numeric values (e.g., score: 84 → score: 85) are considered non-breaking as they enhance the quality of results without changing the response structure or data types.

5. Visual improvements

• Updating mask colors or styling for better visibility.

• Improving mask accuracy or quality.

Best Practices for Integration

To minimize impact from API changes:

• Implement parsing that ignores unknown fields.

• Perform null checks on all nested fields.

• Use semantic versioning and version pinning.

• Check changelog for updates.