Research API Backward Compatibility Strategy

[SueValente]

User Story

In order to avoid breaking existing integrations, developers with legacy code want the old API structure to remain available alongside the new API. WE MAY NOT DO THIS.

Acceptance Criteria

• GIVEN legacy users have code built on old API structure
  WHEN the research is complete
  THEN we have a documented decision on whether to maintain backward compatibility

• GIVEN backward compatibility may be needed
  WHEN evaluating options
  THEN we assess: (1) maintaining both APIs, (2) API versioning, (3) migration timeline with deprecation notices, (4) breaking change communication strategy

• GIVEN a decision is made
  WHEN communicated to stakeholders
  THEN developers understand timeline and migration path

Background

Source: External beta feedback from Chris Marcum (christopher.steven.marcum@gmail.com) - 1/26/2026

Request: Consider retaining the old API structure since many users will have legacy code that will break if the API is changed without backward compatibility.

Considerations:

• Unknown number of users with legacy integrations
• Maintenance burden of supporting two API structures
• Timeline for migration vs immediate breaking change
• Communication and deprecation strategy
• Whether API versioning is feasible (e.g., /v1/ vs /v2/)

Decision points:

• Do we maintain both APIs indefinitely?
• Do we provide migration period with deprecation notices?
• Do we accept breaking changes with comprehensive documentation?
• What's the cost/benefit of each approach?

Security Considerations

Maintaining legacy API endpoints may require security updates to older code. Assess whether old API structure has security implications that would make deprecation preferable to maintenance.

Sketch

• Inventory current API users and usage patterns (if possible via logs/analytics)
• Document differences between old and new API structures
• Research best practices for API deprecation and backward compatibility
• Estimate maintenance cost of supporting both APIs
• Evaluate API versioning implementation options
• Propose decision with timeline and communication strategy
• Get stakeholder input (CDO, OMB councils, TTS leadership)
• Document final decision and create implementation tickets if needed
• Create communication plan for affected users