Reference
Deprecation Policy
Section titled “Deprecation Policy”Purpose and Scope
Section titled “Purpose and Scope”This policy applies to all public, partner, and internal HTTP/REST and event-driven APIs within the Trimble Unity ecosystem. By adhering to these guidelines, Trimble ensures that:
- Consumer breakage is minimized through intentional change management.
- Deprecation and sunsetting schedules are communicated with ample lead time.
- Migration paths are clearly documented and supported.
Core Principles
Section titled “Core Principles”We operate under a “Stability First” philosophy. To ensure your integrations remain functional, we follow these core tenets:
- Backward Compatibility: We prioritize additive, non-breaking changes over architectural resets.
- Successor API Strategy: For major architectural shifts, we do not increment versions within an existing API identity (e.g., we do not simply swap v1 for v2 in a path). Instead, we launch a distinct Successor API to allow side-by-side operation.
- Explicit State Management: Every API exists in a clearly defined state: Active, Deprecated, or Sunset.
- Proactive Communication: We provide predictable timelines and multiple automated and manual reminders before any service retirement.
Defining Change Types
Section titled “Defining Change Types”Understanding the difference between a minor and major change is critical for planning your engineering resources.
Minor Changes (Non-Breaking)
Section titled “Minor Changes (Non-Breaking)”A minor change allows existing clients to continue functioning without code modifications. These changes are typically deployed to Active or Deprecated APIs without prior notice.
Criteria for Minor Changes:
- Adding optional response fields or request parameters with safe defaults.
- Introducing new, independent endpoints.
- Adding new error codes that do not replace existing semantics.
- Performance optimizations or documentation clarifications.
- Relaxing rate limits or validation constraints.
Major Changes (Breaking)
Section titled “Major Changes (Breaking)”A major change is any modification that may cause compile-time or runtime failures, or alter the observable behavior of an existing integration.
Examples of Major Changes:
- Removing or renaming fields, endpoints, or event topics.
- Changing data types, formats (e.g., ISO-8601 string to Epoch), or nullability.
- Altering URI structures or resource identities.
- Modifying default behavior, pagination logic, or sorting orders.
- Tightening validation logic that rejects previously valid inputs.
- Updating Authentication/Authorization requirements.
The Successor API Approach
Section titled “The Successor API Approach”To prevent “breaking the web,” Trimble does not ship major changes into an existing API. Instead:
- New Identity: A breaking change requires a new successor API with a distinct base path or API identity (e.g., a new productized name or subdomain).
- Side-by-Side Availability: The predecessor API remains available in a Deprecated state while the Successor API is Active, allowing you time to migrate.
- Migration Mapping: Every successor API launch includes a comprehensive migration guide mapping old endpoints and fields to the new schema.
API Lifecycle States
Section titled “API Lifecycle States”Active
Section titled “Active”The API is fully supported, stable, and recommended for all new integrations. It receives regular feature enhancements and performance updates.
Deprecated
Section titled “Deprecated”The API remains functional but is considered “feature-frozen.”
- Support: Only critical security or stability fixes are applied.
- Onboarding: New client onboarding is restricted once a Successor API is available.
- Timeline: A specific Sunset Date is announced at the start of this phase.
Sunset
Section titled “Sunset”The API is disabled and no longer reachable.
- Response: Requests to sunset endpoints will return clear error messages with links to migration documentation.
- Availability: Data and functionality must be accessed via the Successor API.
Lifecycle Timelines
Section titled “Lifecycle Timelines”We provide windows for migration based on the impact and usage of the API:
- Standard APIs: 180 days (6 months) notice prior to sunset.
- High-Impact / Strategic APIs: 9–12 months notice prior to sunset.
- Low-Usage / Beta APIs: Minimum 90 days notice.
- Emergency Security/Compliance: In extreme cases (e.g., zero-day vulnerabilities), windows may be shortened with executive oversight and immediate partner notification.
Communication and Awareness
Section titled “Communication and Awareness”We utilize a multi-channel approach to ensure your team is never surprised by a lifecycle change.
Communication Cadence
Section titled “Communication Cadence”- Initial Announcement: At the start of the Deprecation phase.
- Reminders: Periodic notifications at the 90, 60, 30, 14, and 7-day marks.
- Final Notice: Day of sunset.
Channels
Section titled “Channels”- Developer Portal: Official announcements and release notes.
- Direct Email: Notifications sent to the registered administrative and technical contacts for your API keys.
- Unity Construct Release Notes: Scheduled maintenance and retirement notices.
Migration Support
Section titled “Migration Support”To facilitate a smooth transition to successor APIs, Trimble provides:
- Migration Guides: Detailed field-level diffs and behavior mappings.