Draft: Add exceptions to API breaking changes guide
What does this MR do and why?
This adds a new section to the API style guide that documents exceptions to our breaking changes policy. Currently the only exception is for security fixes, where breaking changes may be necessary to protect users and their data.
This addition provides clearer guidance for developers on how to handle the rare cases where breaking API changes cannot be avoided due to security concerns.
This was discussed as part of an MR to remove a filter on the users endpoint
References
- Example MR removing a filter: !190512 (comment 2540840228)
- API style guide about breaking changes: https://docs.gitlab.com/development/api_styleguide/#breaking-changes
- Discussion on Slack (internal only, good for 90 days)
AI summary of the Slack discussion:
This Slack discussion is about handling a breaking change to a REST API endpoint as part of a security fix. Here's the key summary: The Problem:
GitLab needs to remove an optional saml_provider_id attribute from the /users REST endpoint for security reasons This is considered a breaking change, but they don't want to block the security fix Currently, anyone can use this filter, but proper authorization should restrict it to only owners of top-level groups
Options Considered:
Return empty list when attribute is provided Ignore the attribute completely Return 404/400/401 error to notify consumers Add proper authorization complexity to keep the attribute
Final Solution Agreed Upon:
Create a new endpoint: /groups/:id/saml_users with proper authorization Deprecate the old filter: Make the /users endpoint return a 400 error with a helpful message directing users to the new endpoint when saml_provider_id is used Implementation order: Build the new endpoint first, then modify the old one to return the error with guidance
Screenshots or screen recordings
| Before | After |
|---|---|
How to set up and validate locally
MR acceptance checklist
Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.