chore!: change all APIs to v3, or mark them deprecated#2354
Conversation
Reviewer's GuideThis PR upgrades the REST API surface from v2 to v3 by renaming most HTTP paths and OpenAPI operations, deprecating remaining v2 endpoints, and aligning server, tests, CLI, and documentation to consume the new v3 routes, while adding a few new v3 resources and refining some response schemas. Sequence diagram for v2 vs v3 vulnerability analysissequenceDiagram
actor ApiClient
participant HttpServer
participant VulnerabilityEndpointV2
participant VulnerabilityEndpointV3
participant VulnerabilityService
participant Database
ApiClient->>HttpServer: POST /api/v2/vulnerability/analyze
HttpServer->>VulnerabilityEndpointV2: route v2 analyze
VulnerabilityEndpointV2->>VulnerabilityService: analyze_purls_v2(AnalysisRequest)
VulnerabilityService->>Database: query_vulnerabilities_for_purls()
Database-->>VulnerabilityService: vulnerability_matches
VulnerabilityService-->>VulnerabilityEndpointV2: AnalysisResponse
VulnerabilityEndpointV2-->>HttpServer: 200 AnalysisResponse
HttpServer-->>ApiClient: 200 AnalysisResponse (v2, deprecated)
Note over HttpServer,VulnerabilityEndpointV2: Endpoint is marked deprecated and documented as v2/analyze
ApiClient->>HttpServer: POST /api/v3/vulnerability/analyze
HttpServer->>VulnerabilityEndpointV3: route v3 analyze_v3
VulnerabilityEndpointV3->>VulnerabilityService: analyze_purls_v3(AnalysisRequest)
VulnerabilityService->>Database: query_vulnerabilities_for_purls()
Database-->>VulnerabilityService: vulnerability_matches
VulnerabilityService-->>VulnerabilityEndpointV3: AnalysisResponseV3
VulnerabilityEndpointV3-->>HttpServer: 200 AnalysisResponseV3
HttpServer-->>ApiClient: 200 AnalysisResponseV3 (v3)
Note over ApiClient,HttpServer: Clients are expected to migrate from v2 to v3 endpoint
Flow diagram for sbom and related v3 endpointsflowchart LR
subgraph ClientSide["Client side"]
CLI["CLI uses /v3/sbom"]
ApiConsumer["API consumer"]
end
subgraph HttpAPI["HTTP API layer"]
V2SbomList["GET /api/v2/sbom\nreturns PaginatedResults_SbomSummary\ndeprecated"]
V3SbomList["GET /api/v3/sbom\nreturns PaginatedResults_SbomPackageSummary"]
V3SbomUpload["POST /api/v3/sbom\nUpload SBOM"]
V3SbomGet["GET /api/v3/sbom/{id}"]
V3SbomDelete["DELETE /api/v3/sbom/{id}"]
V3SbomDownload["GET /api/v3/sbom/{key}/download"]
V3SbomAdvisory["GET /api/v3/sbom/{id}/advisory"]
V3SbomLicenses["GET /api/v3/sbom/{id}/all-license-ids"]
V3SbomLicenseExport["GET /api/v3/sbom/{id}/license-export"]
V3SbomModels["GET /api/v3/sbom/{id}/models\nGET /api/v3/sbom/models"]
V3SbomPackages["GET /api/v3/sbom/{id}/packages"]
V3SbomRelated["GET /api/v3/sbom/{id}/related"]
V3SbomByPackage["GET /api/v3/sbom/by-package"]
V3SbomCountByPackage["GET /api/v3/sbom/count-by-package"]
end
subgraph Backend["Backend services"]
SbomService["SbomService"]
LicenseService["LicenseService"]
AdvisoryService["AdvisoryService"]
Database[("Database")]
end
CLI --> V3SbomList
ApiConsumer --> V3SbomList
ApiConsumer --> V3SbomUpload
ApiConsumer --> V3SbomGet
ApiConsumer --> V3SbomAdvisory
ApiConsumer --> V3SbomLicenses
ApiConsumer --> V3SbomLicenseExport
ApiConsumer --> V3SbomModels
ApiConsumer --> V3SbomPackages
ApiConsumer --> V3SbomRelated
ApiConsumer --> V3SbomByPackage
ApiConsumer --> V3SbomCountByPackage
V2SbomList -. deprecated .-> V3SbomList
V3SbomList --> SbomService
V3SbomUpload --> SbomService
V3SbomGet --> SbomService
V3SbomDelete --> SbomService
V3SbomDownload --> SbomService
V3SbomByPackage --> SbomService
V3SbomCountByPackage --> SbomService
V3SbomPackages --> SbomService
V3SbomModels --> SbomService
V3SbomRelated --> SbomService
V3SbomAdvisory --> SbomService
V3SbomAdvisory --> AdvisoryService
V3SbomLicenses --> LicenseService
V3SbomLicenseExport --> LicenseService
SbomService --> Database
LicenseService --> Database
AdvisoryService --> Database
File-Level Changes
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- In openapi.yaml the GET /api/v3/sbom endpoint is documented as returning PaginatedResults_SbomPackageSummary, but the handler is still the SBOM listing endpoint (PaginatedResults), so the response schema should be aligned to the actual SBOM summary type rather than a package summary.
- The new v3 advisory listing endpoint in openapi.yaml still uses response descriptions like "Matching vulnerabilities" which looks like a copy-paste artifact from the vulnerability API; it would be clearer to rename these to refer to advisories to avoid confusion for clients.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In openapi.yaml the GET /api/v3/sbom endpoint is documented as returning PaginatedResults_SbomPackageSummary, but the handler is still the SBOM listing endpoint (PaginatedResults<SbomSummary>), so the response schema should be aligned to the actual SBOM summary type rather than a package summary.
- The new v3 advisory listing endpoint in openapi.yaml still uses response descriptions like "Matching vulnerabilities" which looks like a copy-paste artifact from the vulnerability API; it would be clearer to rename these to refer to advisories to avoid confusion for clients.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #2354 +/- ##
==========================================
+ Coverage 70.87% 70.94% +0.06%
==========================================
Files 442 442
Lines 25357 25357
Branches 25357 25357
==========================================
+ Hits 17973 17989 +16
+ Misses 6402 6379 -23
- Partials 982 989 +7 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Claude <noreply@anthropic.com>
|
@ctron this command shows 3 missing parts:
|
carlosthe19916
left a comment
carlosthe19916
left a comment
There was a problem hiding this comment.
@ctron the GET /api/v3/sbom actual response does not match the openapi.yaml.
- openapi.yaml defines the response as:
{
"items": [
{
"group": "string",
"id": "string",
"name": "string",
"version": "string"
}
],
"total": number
}But the actual response of that endpoint is similar to:
{
"items": [
{
"id": "urn:uuid:019e1b0b-c754-79e0-aba5-bd972a955b48",
"document_id": "https://access.redhat.com/security/data/sbom/beta/spdx/quarkus-bom-d6ecbbd9-31bf-46fd-afda-8082120f5260",
"labels": {
"type": "spdx"
},
"data_licenses": [
"CC0-1.0"
],
"published": "2023-11-22T14:00:00Z",
"authors": [
"Organization: Red Hat Product Security (secalert@redhat.com)"
],
"suppliers": [
"Organization: Red Hat"
],
"name": "quarkus-bom",
"number_of_packages": 880,
"sha256": "sha256:4087ad9b170efe11192ff2dd28ec11c3c07e0d859dba42685d2665aa4086bcf8",
"sha384": "sha384:c30e74cb3bb4111476b86b580fc994e8113d1c3f1d128561d79fd12d3b5097f2b7dbd6bc0e5ed7aaaf00a71e1a2d874e",
"sha512": "sha512:47ed78d3f6d37f28df9bd3beb86c609d4e235ff154bdd64f03582970a6d6e9e23a2350a8c55941548a434f92294a0de5f3e416d98212bd18107671feec7b64dd",
"size": 1174356,
"ingested": "2026-05-12T07:16:57.298946Z",
"described_by": [
{
"id": "SPDXRef-d6ecbbd9-31bf-46fd-afda-8082120f5260",
"name": "quarkus-bom",
"group": null,
"version": "2.13.8.Final-redhat-00004"
}
]
},
],
"total": 6
}
|
And because this PR is solving https://redhat.atlassian.net/browse/TC-4296 which is a requirement for the UI ticket https://redhat.atlassian.net/browse/TC-4353 : The endpoint Are you guys aware of it? Is it done consciously and by design? I made a simple test locally using:
The whole analysis took me too much time and I asked AI for a summary, here is the AI summary: V3 Analyze Response Size ProblemSummaryThe 87% of the v3 response is duplicated or deprecated data. The numbersTest input:
Per-chunk breakdown
Three sources of bloat1.
|
| Source of bloat | Size | % of V3 total | Present in V2? |
|---|---|---|---|
remediation.data (mostly product_ids) |
917 KB | 79% | No |
VulnerabilityHead duplication in purl_statuses |
107 KB | 9% | No |
AdvisoryHead repetition in purl_statuses |
44 KB | 4% | Minimal |
| Actual useful new data (status, context, version_range, scores) | ~90 KB | 8% | Partial |
If the duplication and deprecated data field were removed, the v3 response would be ~154 KB instead of 1,157 KB — an 87% reduction.
@ruromero IIRC you worked on this? If so, could you comment on this? |
Co-authored-by: Claude <noreply@anthropic.com>
Good catch. That was indeed a schema issue, due to a wrongly declared return type. Should be fixed now. |
From the DA backend side we require the following data for V3 analyze endpoint (grouped with the categories defined by @carlosthe19916 )
I haven't investigated in Trustify source code the implications and relationships of the purls being requested vs the data retrieved. |
|
@ruromero I tested it with relatively small number of Advisories and saw significant increase of response sizes. It might be out of scope of this PR, but the big sizes already caused me issues locally (broken responses due to some dev proxies while developing - timeouts). In production I anticipate to have latency between client and server that together with bigger responses sizes might have an impact. I'll leave it up to you guys if we want to do something about it. I was just reporting my findings. |
I have just mentioned the data needed/not needed from the DA side. You mentioned most of this is not needed from the UI representation. If we're looking for performance we might need to either find a balance between what's needed from both clients (DA/UI) or define filters or define new endpoints. |
|
If we would make the remediation section optional. Would that solve the issue? @carlosthe19916 |
I think it will definitely reduce the size of the response and help the UI in terms of performance. But even without that change the UI is fine if the endpoint mentioned remains the same. My original intention was just to report something I saw, not to block this PR. My only requirement was the openapi.yaml fix which was fixed already. So I am good with this PR. |
|
@carlosthe19916 awesome. if you have any recommendations, please open a GH issue and we can plan work on it. |
4 participants
See: https://redhat.atlassian.net/browse/TC-4296
Summary by Sourcery
Migrate REST API surface from v2 to v3 endpoints and update OpenAPI spec, handlers, CLI paths, and tests accordingly.
Enhancements: