Skip to content

Add REST API v2 foundation#1245

Merged
sahibamittal merged 14 commits intomainfrom
api-module
Jul 16, 2025
Merged

Add REST API v2 foundation#1245
sahibamittal merged 14 commits intomainfrom
api-module

Conversation

@nscuro
Copy link
Copy Markdown
Member

@nscuro nscuro commented Jun 2, 2025 •
edited
Loading

Description

Adds the api Maven module which generates JAX-RS interfaces and model classes based on an OpenAPI spec in YAML format.

Relevant design decisions:

  • API guidelines are inspired by Zalando's and (partially) codified with spectral.
  • Resource names are pluralized (e.g., teams vs team).
  • Request and response payloads use dedicated objects tailored to the respective operation, instead of re-using the same "domain" objects all over the place.
    • Improves clarity and makes it super obvious which fields are expected or available.
  • List endpoints use keyset pagination and pagination links.
  • All errors occurring in v2 endpoints are communicated with RFC9457-compliant problem details.
  • The new REST API v2 runs in its own servlet.
    • This allows for different sets of filters and exception mappers than v1 to be registered.
  • The OpenAPI spec is split into multiple files to make maintenance easier.
    • It is "collapsed" into a single file during the build.
    • The final OpenAPI spec is uploaded as build artifact in CI.

To demonstrate how APIs may be implemented with this approach, this PR includes a few new endpoints for team management. Those new endpoints are not intended to be "final" yet and are still subject to breaking changes.

Addressed Issue

Implements ADR-007: DependencyTrack/hyades#1797

Relates to DependencyTrack/hyades#1745

Additional Details

DependencyTrack/hyades#1797

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

@nscuro nscuro added the enhancement New feature or request label Jun 2, 2025
@nscuro nscuro force-pushed the api-module branch 8 times, most recently from b98b154 to 5b70a96 Compare June 7, 2025 09:36
@codacy-production
Copy link
Copy Markdown

codacy-production Bot commented Jun 7, 2025 •
edited
Loading

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation Diff coverage
Report missing for 60b47741 ✅ 95.82% (target: 70.00%)
Coverage variation details
Coverable lines Covered lines Coverage
Common ancestor commit (60b4774) Report Missing Report Missing Report Missing
Head commit (8e3e725) 27809 22897 82.34%

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 (#1245) 383 367 95.82%

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%

See your quality gate settings    Change summary preferences

Footnotes

  1. 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. ↩

@nscuro nscuro force-pushed the api-module branch 3 times, most recently from c16bf2d to cc09e59 Compare June 11, 2025 17:17
@nscuro nscuro force-pushed the api-module branch 10 times, most recently from 6c975ae to 4b5bec2 Compare June 27, 2025 09:12
@nscuro nscuro mentioned this pull request Jul 3, 2025
Closed
5 tasks
@nscuro nscuro force-pushed the api-module branch 6 times, most recently from a2632ef to bcb2367 Compare July 5, 2025 12:35
@nscuro nscuro force-pushed the api-module branch 4 times, most recently from ab9ed89 to 6a7c38e Compare July 6, 2025 21:30
@nscuro
Add api module
837a8e7 
Signed-off-by: nscuro <nscuro@protonmail.com>
@nscuro nscuro force-pushed the api-module branch 2 times, most recently from 7c958d3 to 837a8e7 Compare July 7, 2025 09:59
nscuro added 3 commits July 7, 2025 15:51
@nscuro
Run OpenAPI lint workflow for all PRs that modify the spec
cfddf4c 
Signed-off-by: nscuro <nscuro@protonmail.com>
@nscuro
Validate all test responses against OpenAPI spec
c26591f 
Signed-off-by: nscuro <nscuro@protonmail.com>
@nscuro
Add spectral checks for response body schemas
5b0a081 
Signed-off-by: nscuro <nscuro@protonmail.com>
nscuro and others added 5 commits July 7, 2025 23:26
@nscuro
Suppress unknown keyword warnings during OpenAPI validation
0df7c10 
Signed-off-by: nscuro <nscuro@protonmail.com>
@nscuro
Merge branch 'main' of github.com:DependencyTrack/hyades-apiserver in…
c92c43d 
…to api-module
@nscuro
Ensure Jackson exceptions are mapped properly
f098ff0 
Per default Jersey registers default mappers for Jackson exceptions, which cannot be overwritten trivially.

Opting out of those mappers requires manual registration of `JacksonFeature`, which requires manual assembly of a Jersey `ResourceConfig`.

Signed-off-by: nscuro <nscuro@protonmail.com>
@sahibamittal @nscuro
Add endpoints API v2 (#1310)
ec3b757 
Co-authored-by: nscuro <nscuro@protonmail.com>
Signed-off-by: nscuro <nscuro@protonmail.com>
@nscuro
Fix checkstyle issues; Tidy up OpenAPI spec
850dd87 
* Follow kebab-case for spec files: Timestamp -> timestamp
* Resource names should be pluralized: workflow -> workflows
* Use common name for metrics timestamps: measured_at/last_occurrence -> observed_at
* Use `format: uuid` when UUID values are expected
* Fix missing `@PermissionRequired` annotations

Signed-off-by: nscuro <nscuro@protonmail.com>
nscuro added 5 commits July 15, 2025 15:43
@nscuro
Fix invalid schema ref
52cb0d4 
Signed-off-by: nscuro <nscuro@protonmail.com>
@nscuro
Merge branch 'main' of github.com:DependencyTrack/hyades-apiserver in…
9b177aa 
…to api-module
@nscuro
Merge branch 'main' of github.com:DependencyTrack/hyades-apiserver in…
cf76d9e 
…to api-module
@nscuro
Adjust tests for change in portfolio metrics calculation
999eeff 
Signed-off-by: nscuro <nscuro@protonmail.com>
@nscuro
Simplify teams and team-memberships resources
8e3e725 
Save bulk operations for later, keep things simple for the time being.

Signed-off-by: nscuro <nscuro@protonmail.com>
@nscuro
Copy link
Copy Markdown
Member Author

nscuro commented Jul 16, 2025

@sahibamittal I think this is good to go now. Can you have another look if this looks alright to merge?

@nscuro nscuro requested a review from sahibamittal July 16, 2025 08:54
@sahibamittal sahibamittal merged commit a3b16ef into main Jul 16, 2025
9 checks passed
@sahibamittal sahibamittal deleted the api-module branch July 16, 2025 09:50
@nscuro nscuro mentioned this pull request Jul 16, 2025
Merged
2 tasks
@github-actions github-actions Bot locked as resolved and limited conversation to collaborators Aug 15, 2025
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Reviewers

@sahibamittal sahibamittal sahibamittal approved these changes

Assignees

No one assigned

Labels

enhancement New feature or request

Projects

None yet

Milestone

5.6.0

Development

Successfully merging this pull request may close these issues.

2 participants

@nscuro @sahibamittal