Problem Statement
The goal is to evaluate proposed API contract changes for backward compatibility and provide clear guidance to avoid breaking existing client integrations. The workflow must analyze differences between current and proposed endpoints, determine compatibility risks, and generate a migration and testing plan. It should communicate changes precisely and produce client-friendly release notes.
Steps
Ingest Current and Proposed API Contracts
INGESTCollect and parse the current endpoint contract, the proposed updates, client list, and versioning strategy. Normalize the content to ensure all fields and schema definitions are comparable.
Identify Potential Breaking Changes
EXECUTEAnalyze the differences between current and proposed contracts to flag any schema, naming, or behavioral changes that may impact client integrations. Highlight areas that violate the stated versioning strategy.
Generate Compatibility and Migration Recommendations
EXECUTEPropose backward-compatible design options, deprecation paths, and a structured migration plan for affected clients. Ensure recommendations follow constraints such as avoiding breaking changes and using no proprietary identifiers.
Draft Testing Strategy
EXECUTECreate a plan outlining regression tests, contract tests, and client-specific validation steps. Include placeholder examples of test scenarios based on the proposed API changes.
Prepare Client Communications and Release Notes
EXECUTEDraft precise, client-friendly release notes summarizing changes, compatibility considerations, migration timelines, and testing recommendations. Ensure tone is careful and avoids proprietary content.
Prompt Configurations
API Compatibility Review Prompt
You are an API design reviewer. Analyze the provided current API contract, proposed changes, client list, and versioning strategy. Produce: (1) a compatibility assessment; (2) recommended contract design ensuring backward compatibility; (3) a migration plan for clients; (4) a testing plan with placeholder examples; (5) precise, client-friendly release notes. Constraints: do not invent proprietary identifiers; use placeholder examples only; avoid breaking changes whenever possible. Tone: precise, careful, and client-friendly.
Example Inputs/Outputs
Current contract: GET /v1/users returns { "id": "string", "email": "string" }. Proposed contract: GET /v1/users returns { "user_id": "string", "email": "string", "status": "string" }. Clients: clientA, clientB. Versioning strategy: additive changes allowed, breaking changes require new version.
Compatibility assessment: Renaming "id" to "user_id" is a breaking change under stated strategy. Recommended design: retain "id" while adding "user_id" as an optional field, deprecating "id" for future removal. Migration plan: notify clients to switch to "user_id" within a defined timeline using examples such as { "id": "<placeholder-id>", "user_id": "<placeholder-user-id>" }. Testing plan: validate both old and new fields, ensure no clients break. Release notes: describe new field, deprecation, and safe adoption path.