Deprecation: REST API returns 400 for non-numeric IDs on Integer-typed path parameters

Deprecation Summary

Several GitLab REST API endpoints previously accepted non-numeric values in path parameters that are semantically integer IDs. Because these endpoints did not explicitly declare their path parameter types, a non-numeric value (for example --help, null, undefined, or a space-separated list of IIDs like 451 454 458) was either silently coerced or returned a 401/404/200 response.

With this change, integer-typed path parameters are now validated. Requests that pass a non-numeric value to an Integer-typed path parameter will now receive 400 Bad Request instead of 401 Unauthorized, 404 Not Found, or (in rare, latent-bug cases) 200 OK.

This is a correctness improvement: 400 Bad Request is the appropriate response for a malformed identifier. Analysis of production traffic (GitLab.com) 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, and those are already-malformed requests. Every other affected request (< 70/day) is already failing today and only changes which 4xx code it receives.

Affected endpoints (Integer-typed path parameters):

  1. GET/PUT projects/:id/merge_requests/:merge_request_iid/approvals (merge_request_iid)
  2. GET personal_access_tokens/:id (id)
  3. admin/batched_background_migrations (id)
  4. admin/migrations (timestamp)
  5. hooks/resend_hook (hook_id, hook_log_id)
  6. group_boards (board_id)
  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)

Documentation on feature being deprecated

Migration guidelines

Send a numeric ID, which every legitimate client already does. For the previously-lenient multi-IID requests (e.g. 451 454 458), send one IID per request.

Migration is trivial to none for valid clients: 400 Bad Request is the more correct response for a malformed ID, and well-formed requests are unaffected.

No automated migration is required or performed.

Background

Approximately 10% of GitLab's API files contained endpoints that did not declare the parameters they accept, so the generated OpenAPI specification did not include type information for those path parameters (emitting schema: {}). This made the API harder to consume programmatically.

Declaring the path parameter types (see !238289 (merged) and !238294 (merged)) fixes the generated OpenAPI spec and enables proper validation. A side effect is that Integer-typed path parameters now reject non-numeric input with 400 Bad Request.

This deprecation was approved as a breaking-change exception under the "negligible customer impact" criterion. See the internal breaking change request: gitlab-com/Product#14561 (closed).

Breaking Change?

Does this deprecation contain a breaking change? Yes

Affected Customers

Who is affected by this deprecation: GitLab.com users, Self-managed users, or Dedicated users? (choose all that apply)

  • GitLab.com
  • Self-managed
  • Dedicated

What pricing tiers are impacted?

  • GitLab Free
  • GitLab Premium
  • GitLab Ultimate

Deprecation Milestone

This deprecation is being announced in milestone: xx.xx

Planned Removal Milestone

The feature / functionality will be removed in milestone: xx.xx

Rollout Plan

  • DRI Engineers: @abignotti

  • DRI Engineering Manager: @EM

  • Describe rollout plans on GitLab.com

    • Link to a feature flag rollout issue that covers:
      • Expected release date on GitLab.com and GitLab version
      • Rollout timelines, such as a percentage rollout on GitLab.com
      • Creation of any clean-up issues, such as code removal

Communication Plan

  • DRI Product Manager: @PM

An internal slack post and a release post are not sufficient notification for our customers or internal stakeholders. Plan to communicate proactively and directly with affected customers and the internal stakeholders supporting them.

Internal Communication Plan

  • Support Preparedness issue created
  • Guidance for Engineering, Product, Security, Customer Success, and Sales created

External Communication Plan

  • Customer announcement plan
    • Document the migration plan for users, clearly outlining the actions they need to take to mitigate the impact of the breaking change.
    • A deprecation announcement entry has been created so the deprecation will appear in release posts and on the general deprecation page. Add link to the relevant merge request.
    • Documentation has been updated to mark the feature as deprecated. Add link to the relevant merge request.
  • On the major milestone:
    • The deprecated item has been removed. Add link to the relevant merge request.
    • If the removal of the deprecated item is a breaking change, the merge request is labeled breaking change.

References