Tweak /api/v2/components endpoint

[nscuro]

Description

Tweaks /api/v2/components endpoint as follows:

• Encodes matching semantics in query parameter names to make them explicit.
• Removes the project_uuid parameter. We already have the /api/v2/projects/<uuid>/components endpoint for this.
• Change cpe filter from "contains" to "equals" semantics. We validate that the provided value is a valid CPE, and a partial CPE will fail to parse. Neither "contains" nor "prefix" matching makes sense there.
• Updates API description to mention that CPE and PURL must be valid, and that hash_type is required when hash is provided.
• Removes sorting by SWID Tag ID. There's no index on that column, and SWID usage has not been widespread enough to justify committing to support this yet.

Addressed Issue

Relates to #1867

Additional Details

Frontend PR: DependencyTrack/hyades-frontend#489

Checklist

• I have read and understand the contributing guidelines
• This PR fixes a defect, and I have provided tests to verify that the fix is effective
• This PR implements an enhancement, and I have provided tests to verify that it works as intended
• This PR introduces changes to the database model, and I have updated the migration changelog accordingly
• This PR introduces new or alters existing behavior, and I have updated the documentation accordingly

[codacy-production]

Up to standards ✅

🟢 Issues 2 medium

Results:
2 new issues

Category	Results
Complexity	2 medium

View in Codacy

🟢 Metrics 0 complexity

Metric	Results
Complexity	0

View in Codacy

🟢 Coverage 85.71% diff coverage

Metric	Results
Coverage variation	Report missing for d0b67761
Diff coverage	✅ 85.71% diff coverage (70.00%)

View coverage diff in Codacy

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (d0b6776)	Report Missing	Report Missing	Report Missing
Head commit (069eb1c)	43009	36217	84.21%

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#2000)	7	6	85.71%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

¹ Codacy didn't receive coverage data for the commit, or there was an error processing the received data. Check your integration for errors and validate that your coverage setup is correct.

_{TIP This summary will be updated as you push new changes. Give us feedback}

[Copilot]

Pull request overview

This PR tweaks the /api/v2/components listing endpoint to make filter semantics explicit in parameter names, remove project_uuid filtering, tighten CPE matching semantics, and update API documentation/tests accordingly.

Changes:

• Rename text filter query parameters to explicit *_contains / purl_prefix semantics and remove project_uuid support.
• Change CPE filtering from substring match to case-insensitive exact match and drop swid_tag_id as a sortable field.
• Update OpenAPI docs and adjust v2 resource tests for the new query parameter names and behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
apiserver/src/main/java/org/dependencytrack/resources/v2/ComponentsResource.java	Updates v2 endpoint parameters (remove project UUID filter, rename filters) and passes new filters into DAO.
apiserver/src/main/java/org/dependencytrack/persistence/jdbi/ComponentDao.java	Switches CPE filtering to exact match and removes SWID Tag ID from supported sorting.
apiserver/src/test/java/org/dependencytrack/resources/v2/ComponentsResourceTest.java	Updates tests to use renamed query parameters and removes project_uuid-specific tests.
api/src/main/openapi/paths/components.yaml	Updates /components OpenAPI definition to match new parameter names/semantics and sortable fields.

Comments suppressed due to low confidence (1)

apiserver/src/main/java/org/dependencytrack/resources/v2/ComponentsResource.java:123

• cpe is only checked for != null, but then trimToNull(cpe) is passed to CpeParser.parse(...). If a client sends a whitespace-only cpe, trimToNull becomes null and CpeParser.parse(null) may throw an NPE (500) instead of returning a 400. Consider trimming first and treating blank as absent (or rejecting it explicitly).

                try {

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.