# Breaking Change Exception Request ## Executive summary \~10% of GitLab's API files contain endpoints that don't specify the parameters they accep, so the API specification does not include it either. In some cases this makes it difficult for clients to consume the API. Fixing this implies that in some specific cases (detailed below) requests may receive either: 1. `400 Bad Request` instead of `401 Unauthorized` / `404 Not Found` 2. `400 Bad Request` instead of `200 Ok` Production traffic analysis shows the real-world impact is negligible: on the highest-traffic affected endpoint (31.2M requests / 7 days), only \~4 requests per day change from a success to an error; _those are already-malformed requests_. Every other affected request (\< 70 / day) is already failing today and only changes which 4xx code it receives. ### Does your breaking change meet one of these three criteria? 1. The impact of the breaking change has been **fully mitigated via an automated migration** that requires no action from the customer. 2. The breaking change will have **negligible customer impact** as measured by actual product usage tracking across Self-Managed, GitLab.com, and Dedicated. For instance if it impacts less than 1% of the GitLab customer base. 3. The breaking change is being implemented due to a **significant security risk**- Severity 1 or 2. [Deprecation guidelines](https://docs.gitlab.com/development/deprecation_guidelines/) **Yes — criterion 2: negligible customer impact (well under 1% of usage).** Measured impact is a few requests per day on the busiest affected route, none from legitimate happy-path clients. ## Impact assessment Quantified on the two highest-traffic affected routes via production request logs (Kibana, GitLab.com): - **`GET/PUT projects/:id/merge_requests/:merge_request_iid/approvals`** (31.2M requests / 7 days). In a 24h window, 68 requests would see a changed status: - **64**: `404 -> 400` — already errors today (`--help` from CLI misuse, `null`/`undefined` from JS bugs). No behavioral loss. - **4**: `200 -> 400` — space-separated multi-IID values (e.g. `451 454 458`) that "succeed" today only because a lenient cast silently picks the first IID (**a latent bug**). These are the only requests that move from success to failure. - **`GET personal_access_tokens/:id`** In a 7 days window, 23 requests would see a changed status, but all were fuzzer/XSS probe traffic, with only a single authenticated session. 0 legitimate, well-formed requests were affected. The remaining \~9 affected endpoints are much lower traffic and are expected to follow the same pattern (non-numeric path input is overwhelmingly malformed or automated probe traffic). No specific customer tier/ARR is implicated. Affected endpoints: 1. `personal_access_tokens` (`id`) 2. `admin/batched_background_migrations` (`id`) 3. `admin/migrations` (`timestamp`) 4. `hooks/resend_hook` (`hook_id`, `hook_log_id`) 5. `group_boards` (`board_id`) 6. `merge_request_approvals` (`merge_request_iid`) 7. `project_hooks` (`hook_id` on the `…/:hook_id/events` route) 8. `group_hooks` (`hook_id`) 9. `vulnerability_exports` (`id`) 10. `virtual_registries/packages/maven/endpoints` (`id`) 11. `admin/search/zoekt` (`project_id`, `node_id`, `namespace_id`) ### How many users and customers are impacted? What Tier/ARR of customer? ### Can we get the same outcome without a breaking change? Not without sacrificing API ### When do you want to make the breaking change? The change is ready (https://gitlab.com/gitlab-org/gitlab/-/merge_requests/238289, with batch 2 at https://gitlab.com/gitlab-org/gitlab/-/merge_requests/238294). Given the small impact we would like to ship in a near-term release. ### What is the alternative for customers to do the same job the change will break? Send a numeric ID, which every legitimate client already does. For the handful of multi-IID requests, send one IID per request. ### How difficult is it for customers to migrate to the alternative? Is there a migration plan? Trivial to none for valid clients. `400` is the more correct response for a malformed ID. ### Does this breaking change interact with [other proposed or approved breaking changes?](https://gitlab.com/gitlab-com/Product/-/boards/9741901) None known. ## Rollout & Communication plan ### Have we handled similar breaking changes in the past? What can we learn from the success or failure of those methods? This request is intended to establish an audit trail rather than relying on that informal precedent, and (if approved) we will update the [API Style Guide](https://docs.gitlab.com/development/api_styleguide/#what-is-a-breaking-change) to clarify the treatment of `4xx` -\> `4xx` changes. ### Are you employing any strategies to lessen the customer or support impact? No. ### Internal Communication ### Customer Communication Given \<1% impact, the proposed method is a deprecation/release-post note rather than direct outreach. To be confirmed with the Customer Comms process. ## Approval Process - [x] Tag in the appropriate Product Director and Engineering Director for your product area. - [x] Approved by **Product Director or GPM**: Sam Wiskow - [x] Approved by **Engineering Director**: Chris Sanders - [x] Once approved by both, add the label "Breaking Change: Awaiting Support Approval" and remove the prior label. - [x] Share in [#support_leadership](https://gitlab.enterprise.slack.com/archives/C01F9S37AKT) and get sign-off from 1 Support Senior Leader, then add "Breaking Change: Awaiting VP Approval". - [x] Approved by **Support Senior Manager or Director**: Johnny Scarborough - [x] Tag in the appropriate Product and Engineering VPs or Senior Directors. - [x] Approved by **Product VP or Senior Director**: Oren Ben Shaul - [x] Approved by **Engineering VP or Senior Director**: Mani Sundaram - [x] Once VP-approved, add the "Breaking Change: VP Approved" label and keep this issue open until implemented. - [x] Create a [public deprecation issue](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Deprecations.md) as the customer source of truth. - [x] Add the change to the deprecations docs page.