API Versioning & Upgrade Policy

Platform Stability Commitment

Admoai follows a "minimize versions" philosophy inspired by SaaS industry leaders. We evolve continuously without forcing disruptive migrations on our customers.

Version Status Dashboard

Version	Release Date	Current Phase	Support Until	Status
2025-11-01	Nov 1, 2025	Active	Nov 1, 2026+	🟢 Recommended
2025-01-01	Jan 1, 2025	Active	Jan 1, 2026+	🟢 Supported

Overview

At Admoai, we believe that API stability and continuous innovation are not mutually exclusive. Our versioning strategy is designed to:

Maximize backward compatibility across releases

Minimize breaking changes that require customer action

Enable rapid feature delivery without version sprawl

Reduce integration maintenance burden for developers

This document outlines our versioning policy and the expectations we have for API integrators.

Version Philosophy

The Problem with Traditional Versioning

Many platforms follow a traditional versioning approach where:

Each major change requires a new version (v1, v2, v3...)

Customers must rewrite integrations to adopt new features

Old versions become deprecated quickly, forcing migrations

Teams spend more time on maintenance than innovation

Result: High integration costs, migration fatigue, and slower feature adoption.

Our "Minimize Versions" Approach

Admoai takes a different path:

Additive changes only: New fields and features are added, existing ones remain stable

Long version lifecycles: Versions remain active for 12+ months minimum

Graceful evolution: Changes are designed for zero-downtime adoption

Clear migration paths: When changes are needed, we provide comprehensive guides

Result: Lower total cost of ownership, faster time-to-value, predictable upgrade cycles.

How Versions Work

Date-Based Versioning

We use calendar versioning in the format YYYY-MM-DD:

Benefits:

Transparent: Version date = feature freeze date

Predictable: Easy to understand age and support status

Flexible: Allows targeted updates without full API rewrites

Version Selection

Clients specify their version via HTTP headers:

Default Behavior

If no version header is provided, the system defaults to the oldest active version for maximum backward compatibility.

Tolerant Reader Policy

To maintain our minimize-versions philosophy, we require all API integrators to follow the Tolerant Reader Pattern. This industry-standard practice ensures your integration remains resilient to non-breaking API evolution.

What is Tolerant Reader?

The Tolerant Reader Pattern means your code should:

Accept more than it expects

Ignore what it doesn't understand

Validate only what matters to its logic

The Four Golden Rules

Rule 1: Ignore Unknown Fields

Requirement: Your code MUST ignore JSON fields it doesn't recognize.

Why: We add new fields frequently (e.g., metadata, analytics hints). Your integration shouldn't break when we ship improvements.

Example: When we added metadata.duration for video ads, integrations following this rule continued working seamlessly.

Rule 2: Handle Unexpected Enum Values

Requirement: Treat enumerations as open sets, not closed lists.

Why: We may introduce new enum values (e.g., new delivery modes, event types, targeting options) without bumping the version.

Example: If we add vast_wrapper delivery mode, your integration should handle it gracefully, not crash.

Rule 3: Treat Objects as Extensible

Requirement: Don't assume JSON objects have a fixed structure.

Why: We extend objects with new optional fields (e.g., adding metadata to Creative). Your schema validation shouldn't reject responses with extra data.

Pro Tip: Use TypeScript's Pick<> or Partial<> utilities to select only the fields you need.

Rule 4: Validate Only What Matters

Requirement: Validate business logic constraints, not API contract completeness.

Why: We may add new required fields that don't affect your use case. Over-validation creates artificial breaking changes.

Best Practice: Validate the minimum viable data needed for your feature, nothing more.

Change Types & Compatibility

Additive Changes (Non-Breaking)

These changes do NOT require a new version:

Change Type	Example	Your Action
New optional field	Adding `metadata.format`	None (ignored automatically)
New enum value	Adding `"vast_wrapper"` to delivery	Handle gracefully with default case
New endpoint	Adding `POST /v1/analytics`	None (opt-in when ready)
New response object	Adding `recommendations` array	None (ignored automatically)
New error code	Adding error code `10999`	Handle as generic error
New warning	Adding new warning type	Log and continue

Zero-Downtime Adoption

Additive changes are designed for zero-downtime adoption. Update when convenient, not urgently.

Breaking Changes (Version Bump Required)

These changes require a new version:

Change Type	Example	Mitigation
Removing field	Removing `metadata.language`	12-month deprecation notice
Changing field type	`count: string → number`	New version + migration guide
Renaming field	`user.id → user.userId`	New version + mapping docs
Removing enum value	Removing `"legacy"` delivery	12-month deprecation notice
Changing validation	Making optional field required	New version + transition period

Breaking Change Policy

Breaking changes trigger a new API version with:

12+ months of parallel support

Migration guide with code examples

Deprecation warnings in old version responses

Automated migration tools (when feasible)

Version Lifecycle

Support Timeline

Phase Definitions

1. Active Phase (12+ months)

Full feature support: New features added

Bug fixes: Issues resolved promptly

Performance improvements: Optimizations applied

Security updates: Patches applied immediately

Documentation updates: Kept current

Recommended

Integrate new projects with the latest Active version.

2. Maintenance Phase (6 months)

Bug fixes: Critical issues only

Security updates: Patches applied immediately

⚠️ No new features: Feature development frozen

⚠️ Migration encouraged: Start planning upgrade

Deprecation Warning

Responses include X-API-Deprecated: true header with sunset date.

3. Deprecated Phase (3 months)

Security updates: Critical patches only

⚠️ No bug fixes: Non-security issues not addressed

⚠️ Limited support: Best-effort support only

🔴 Sunset date announced: Hard deadline communicated

Action Required

Migrate immediately to avoid service disruption.

4. Sunset (End of Life)

🔴 Service terminated: API version no longer accepted

🔴 Requests rejected: HTTP 410 Gone returned

🔴 No support: Integration assistance unavailable

Breaking Change

Requests with sunset version headers return:

{
  "success": false,
  "errors": [{
    "code": 10043,
    "message": "API version 2024-01-01 is no longer supported. Please upgrade to 2025-01-01 or later.",
    "details": {
      "deprecated_version": "2024-01-01",
      "active_versions": ["2025-01-01", "2025-11-01"],
      "migration_guide": "https://docs.admoai.com/migration-guide"
    }
  }]
}

Best Practices for Integrators

1. Version Pinning Strategy

Recommendation: Pin to a Specific Version

Why:

Predictable behavior across deployments

Controlled upgrade timing

Easier debugging and testing

Dont Rely on Defaults

Relying on the default version can lead to unpredictable behavior when defaults change.

2. Defensive Programming

Always Use Optional Chaining

Why: Protects against schema evolution and missing fields.

3. Graceful Degradation

Provide Fallbacks for Unknown Values

Why: Maintains service continuity during API evolution.

4. Monitor Warnings

Log and Track API Warnings

Why: Early detection of upcoming changes or integration issues.

Proactive Monitoring

Set up alerts for API warnings to catch potential issues before they become problems.

5. Automated Testing Across Versions

Test Against Multiple Versions in CI/CD

Why: Ensures smooth version transitions and catches breaking changes early.

Migration Process

When we release a new version, here's what happens:

Step 1: Announcement (T-90 days)

Email/Slack notification to all registered developers

Migration guide published with code examples

Step 2: Parallel Support (T-0 to T+12 months)

Both versions active: Old and new versions fully supported

No forced migration: Integrate on your timeline

Testing period: Validate new version in staging

Support available: Engineering assistance via Slack/email

Step 3: Maintenance Phase (T+12 to T+15 months)

⚠️ Old version enters maintenance: Feature freeze

⚠️ Deprecation warnings: Headers added to responses

⚠️ Migration encouraged: Upgrade before sunset

Security updates: Still applied to old version

Step 4: Deprecation Notice (T+15 months)

🔴 Sunset date announced: 90-day hard deadline

🔴 Aggressive warnings: Email + in-response notices

🔴 Support limited: Best-effort only

Migration tooling: Automated upgrade scripts (if applicable)

Step 5: Sunset (T+18 months)

🔴 Version terminated: HTTP 410 Gone for old version

🔴 Breaking change: Must upgrade to continue service

New version mature: 12+ months of production use

Migration Timeline

Minimum 21 months from new version release to old version sunset.

SDK Version Alignment

Our official SDKs automatically handle versioning:

SDK Version Strategy:

Major SDK version = API version (e.g., SDK v2025.11.x → API v2025-11-01)

Automatic upgrades: Minor/patch updates maintain compatibility

Migration notices: Breaking SDK updates include upgrade guides

Frequently Asked Questions

Q: What if I need a feature from a new version?

Answer:

Simply update your version header to the new version:

If using SDK: Update to newer SDK version:

Q: Can I use different versions for different endpoints?

Answer:

Yes! Version headers are per-request:

This allows gradual migration per endpoint/feature.

Q: How do I know when to upgrade?

Indicators it's time to upgrade:

Response includes deprecation warning header

Email notification about upcoming sunset

New features you want to adopt

Bug fixes only available in newer version

When NOT to upgrade:

Current version in Active phase

No features needed from new version

No deprecation warnings received

Q: What happens if I don't upgrade before sunset?

Answer:

Your API requests will fail with HTTP 410 Gone:

{
  "success": false,
  "errors": [{
    "code": 10043,
    "message": "Version 2024-01-01 is no longer supported",
    "details": {
      "sunset_date": "2026-01-01",
      "migration_guide": "https://docs.admoai.com/..."
    }
  }]
}

Prevention Strategy

We send multiple warnings 90, 60, 30, and 7 days before sunset. Don't ignore them!

Q: Do you support version ranges (e.g., `>=2025-01-01`)?

Answer:

No. We require exact version for predictability:

Why:

Ensures reproducible behavior

Prevents unexpected breaking changes

Enables better caching and routing

Contact & Support

Need help with versioning or migration?

Technical Support: support@admoai.com

API Versioning & Upgrade Policy

Version Status Dashboard#

Overview#

Version Philosophy#

The Problem with Traditional Versioning#

Our "Minimize Versions" Approach#

How Versions Work#

Date-Based Versioning#

Version Selection#

Tolerant Reader Policy#

What is Tolerant Reader?#

The Four Golden Rules#

Rule 1: Ignore Unknown Fields#

Rule 2: Handle Unexpected Enum Values#

Rule 3: Treat Objects as Extensible#

Rule 4: Validate Only What Matters#

Change Types & Compatibility#

Additive Changes (Non-Breaking)#

Breaking Changes (Version Bump Required)#

Version Lifecycle#

Support Timeline#

Phase Definitions#

1. Active Phase (12+ months)#

2. Maintenance Phase (6 months)#

3. Deprecated Phase (3 months)#

4. Sunset (End of Life)#

Best Practices for Integrators#

1. Version Pinning Strategy#

2. Defensive Programming#

3. Graceful Degradation#

4. Monitor Warnings#

5. Automated Testing Across Versions#

Migration Process#

Step 1: Announcement (T-90 days)#

Step 2: Parallel Support (T-0 to T+12 months)#

Step 3: Maintenance Phase (T+12 to T+15 months)#

Step 4: Deprecation Notice (T+15 months)#

Step 5: Sunset (T+18 months)#

SDK Version Alignment#

Frequently Asked Questions#

Q: What if I need a feature from a new version?#

Q: Can I use different versions for different endpoints?#

Q: How do I know when to upgrade?#

Q: What happens if I don't upgrade before sunset?#

Q: Do you support version ranges (e.g., >=2025-01-01)?#

Contact & Support#

Version Status Dashboard

Overview

Version Philosophy

The Problem with Traditional Versioning

Our "Minimize Versions" Approach

How Versions Work

Date-Based Versioning

Version Selection

Tolerant Reader Policy

What is Tolerant Reader?

The Four Golden Rules

Rule 1: Ignore Unknown Fields

Rule 2: Handle Unexpected Enum Values

Rule 3: Treat Objects as Extensible

Rule 4: Validate Only What Matters

Change Types & Compatibility

Additive Changes (Non-Breaking)

Breaking Changes (Version Bump Required)

Version Lifecycle

Support Timeline

Phase Definitions

1. Active Phase (12+ months)

2. Maintenance Phase (6 months)

3. Deprecated Phase (3 months)

4. Sunset (End of Life)

Best Practices for Integrators

1. Version Pinning Strategy

2. Defensive Programming

3. Graceful Degradation

4. Monitor Warnings

5. Automated Testing Across Versions

Migration Process

Step 1: Announcement (T-90 days)

Step 2: Parallel Support (T-0 to T+12 months)

Step 3: Maintenance Phase (T+12 to T+15 months)

Step 4: Deprecation Notice (T+15 months)

Step 5: Sunset (T+18 months)

SDK Version Alignment

Frequently Asked Questions

Q: What if I need a feature from a new version?

Q: Can I use different versions for different endpoints?

Q: How do I know when to upgrade?

Q: What happens if I don't upgrade before sunset?

Q: Do you support version ranges (e.g., `>=2025-01-01`)?

Contact & Support