Issue
The Migrating From REST API V3 section currently documents new, moved, and removed endpoints, including V3-to-V4 endpoint mappings.
However, it does not document changes to the attributes within each endpoint’s request and response.
Customers must therefore compare the V3 and V4 Swagger definitions side by side to identify:
- Added, removed, or renamed attributes
- Changes to required and optional fields
- Changes to object nesting and response structure
- Changes to parameters
This makes migrations time-consuming and increases the risk of missed changes, integration failures, delayed upgrades, and support cases.
Proposed solution
For each endpoint mapping, include a concise table showing attribute changes. If no attributes changed, state: “No request or response schema changes”
This should become a standard part of future major-version migration documentation, including V4-to-V5.
Benefits
- Reduces migration time and manual comparison
- Prevents customers from overlooking breaking changes
- Makes upgrade effort easier to estimate
- Reduces testing, troubleshooting, and support cases
- Creates a consistent process for future API migrations