Breaking change: rename Vulnerabilities API to Vulnerability Findings API
Problem to solve
During the review of Create a Vulnerability from Finding (API call for the backstage implementation of the First-class Vulnerabilities MVC), the maintainer had raised a hand about the inconsistency in the /projects/:id/vulnerabilities endpoint behavior. This API path currently returns different types of objects depending on the first_class_vulnerabilities feature flag state: Vulnerability instances in case first_class_vulnerabilities is enabled and Vulnerabilities::Occurrence instances otherwise.
first_class_vulnerabilities feature flag controls the availability of the upcoming MVC Standalone Vulnerability objects (aka First-class Vulnerabilities) functionality.
Intended users
Proposal
There was a decision to reserve the /projects/:id/vulnerabilities for serving the Vulnerability instances only regardless of the first_class_vulnerabilities feature flag state. The current implementation of it is moved to /projects/:id/vulnerability_findings API path.
Thus, the projects/:id/vulnerabilities will be consistent in terms of responding only with Vulnerability objects when first_class_vulnerabilities feature flag is enabled and with 404 Not Found otherwise.
Initially, this change was planned to be covered with a feature flag and released together with #13561 (closed). This decision makes this change immediate breaking change for the current Vulnerabilities API consumers.
To be noted:
- current Vulnerabilities API is in the Alpha stage and the warning about possible breaking changes is explicit
- this API is used by GitLab frontend, the corresponding changes were made to switch the API path used
Permissions and Security
The permissions for the Vulnerability Findings API will be the exact copy of the current Vulnerabilities API: a user would have to be able to read_project_security_dashboard to access the Vulnerability Findings API.
Documentation
-
Move the contents of the Vulnerabilities API docs page to the newly created Vulnerability Findings API docs page -
On that page, rename all mentions of the "vulnerabilities" to be "vulnerability findings" -
Leave a renaming notice with a link on the former Vulnerabilities API docs page -
Rename the Vulnerabilities to Vulnerability Findings on the API resources list page
Testing
API endpoints' tests are updated for both projects/:id/vulnerabilities and projects/:id/vulnerability_findings to reflect these changes.
What does success look like, and how can we measure that?
The projects/:id/vulnerabilities is consistent in terms of responding only with Vulnerability objects when first_class_vulnerabilities feature flag is enabled and with 404 Not Found otherwise.