chore(api): Handle deprecated and non-functional endpoints - BED-3312 #2258
Conversation
cami-specter
added
documentation
WalkthroughThis PR reactivates nine deprecated /api/v2/tasks/* endpoints, adds a new GET /api/v2/tasks/available path, and updates descriptions of three endpoints with deprecation notices and migration guidance. All edits are OpenAPI metadata; no business logic or data model changes. Changes
Sequence Diagram(s)(omitted) Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
cami-specter
changed the title
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Fix all issues with AI agents
In `@packages/go/openapi/src/paths/analysis.asset-groups.id.combo-node.yaml`:
- Around line 30-31: The YAML description block contains extra spaces after the
colon ("description: >") causing yamllint warnings; open the YAML for the
OpenAPI path and change the key to use a single space before the block scalar
(i.e., "description: >") so the description uses the folded scalar correctly;
update the "description" entry in the analysis.asset-groups.id.combo-node.yaml
file (the description: > line) to remove the extra space.
In `@packages/go/openapi/src/paths/clients.clients.id.completed-tasks.yaml`:
- Around line 31-33: The YAML lint error is caused by extra spaces after the
description key before the block scalar indicator; update the description
mapping by removing the extra spaces so the line reads with a single space
between the key and the block indicator (i.e., change "description: >" to
"description: >") for the completed-tasks endpoint's description block to
satisfy YAMLlint (refer to the description key/block scalar in
clients.clients.id.completed-tasks.yaml).
In `@packages/go/openapi/src/paths/clients.clients.id.tasks.yaml`:
- Around line 31-33: The YAML description block has extra spaces after the colon
("description: >") causing yamllint spacing errors; update the key to remove
the extra space so it reads "description: >" (i.e., ensure a single space or no
space between the colon and block scalar indicator) for the
clients.clients.id.tasks.yaml description entry to satisfy YAML linting.
In `@packages/go/openapi/src/paths/tasks.tasks.available.yaml`:
- Around line 58-79: The responses for the tasks.tasks.available endpoint are
missing a 429 rate-limit response; add a 429 entry under the responses block for
the path defined in packages/go/openapi/src/paths/tasks.tasks.available.yaml so
it mirrors tasks.tasks.finished. Specifically, insert a 429 response reference
consistent with other endpoints (e.g., $ref:
'./../responses/too-many-requests.yaml' or the existing 429 response used by
tasks.tasks.finished) under the responses mapping for the
200/400/401/403/404/500 entries so the endpoint documents rate-limiting
consistently.
In `@packages/go/openapi/src/paths/tasks.tasks.current.yaml`:
- Around line 29-48: This endpoint's OpenAPI responses omit a 429 Too Many
Requests entry, causing inconsistency with other task endpoints; update
packages/go/openapi/src/paths/tasks.tasks.current.yaml (the GET /tasks/current
deprecated endpoint) by adding a 429 response entry referencing the shared 429
response (e.g., ../responses/too-many-requests.yaml) under the responses block
so it matches the pattern used by finished/id/id.cancel/id.log/main task
endpoints, or alternatively add a short comment in the file explaining why 429
is intentionally omitted due to deprecation and parity with GET
/api/v2/jobs/current.
In `@packages/go/openapi/src/paths/tasks.tasks.id.log.yaml`:
- Around line 37-58: Add a 400 Bad Request response entry to the responses list
in tasks.tasks.id.log.yaml to mirror the other task endpoints; insert a "400:"
mapping (e.g. 400: $ref: './../responses/bad-request.yaml') alongside the
existing 401/403/404/429/500 entries so the GET /api/v2/tasks/{task_id} log
response follows the same invalid task_id pattern used by GET
/api/v2/tasks/{task_id} and PUT /api/v2/tasks/{task_id}/cancel.
In `@packages/go/openapi/src/paths/tasks.tasks.yaml`:
- Around line 56-67: Add the same pagination query parameters and response
envelope used in tasks.tasks.finished.yaml: add `skip` and `limit` query
parameters to this endpoint's parameters list and change the 200 response schema
to reference the pagination envelope `api.response.pagination.yaml` with its
`data` items pointing to ./../schemas/model.client-scheduled-job-display.yaml;
ensure the envelope structure matches the finished endpoint so clients receive
paginated metadata plus the array of scheduled-job-display items.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (14)
packages/go/openapi/doc/openapi.jsonpackages/go/openapi/src/openapi.yamlpackages/go/openapi/src/paths/analysis.asset-groups.id.combo-node.yamlpackages/go/openapi/src/paths/clients.clients.id.completed-tasks.yamlpackages/go/openapi/src/paths/clients.clients.id.tasks.yamlpackages/go/openapi/src/paths/tasks.tasks.available.yamlpackages/go/openapi/src/paths/tasks.tasks.current.yamlpackages/go/openapi/src/paths/tasks.tasks.end.yamlpackages/go/openapi/src/paths/tasks.tasks.finished.yamlpackages/go/openapi/src/paths/tasks.tasks.id.cancel.yamlpackages/go/openapi/src/paths/tasks.tasks.id.log.yamlpackages/go/openapi/src/paths/tasks.tasks.id.yamlpackages/go/openapi/src/paths/tasks.tasks.start.yamlpackages/go/openapi/src/paths/tasks.tasks.yaml
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-08-28T16:43:43.961Z
Learnt from: mvlipka
Repo: SpecterOps/BloodHound PR: 1784
File: packages/go/openapi/doc/openapi.json:18008-18029
Timestamp: 2025-08-28T16:43:43.961Z
Learning: In SpecterOps/BloodHound, packages/go/openapi/doc/openapi.json is generated from YAML under packages/go/openapi/src/schemas; edits must be made to the YAML and then the spec regenerated.
Applied to files:
packages/go/openapi/src/paths/tasks.tasks.start.yamlpackages/go/openapi/src/paths/tasks.tasks.end.yamlpackages/go/openapi/src/openapi.yaml
🪛 YAMLlint (1.37.1)
packages/go/openapi/src/paths/analysis.asset-groups.id.combo-node.yaml
[warning] 30-30: too many spaces after colon
(colons)
packages/go/openapi/src/paths/clients.clients.id.completed-tasks.yaml
[warning] 31-31: too many spaces after colon
(colons)
packages/go/openapi/src/paths/clients.clients.id.tasks.yaml
[warning] 31-31: too many spaces after colon
(colons)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: Build BloodHound Container Image / Build and Package Container
- GitHub Check: build-ui
- GitHub Check: run-tests
- GitHub Check: run-analysis
🔇 Additional comments (18)
packages/go/openapi/src/paths/tasks.tasks.start.yaml (1)
17-48: LGTM — deprecated task start path is clearly documented.
Deprecation guidance and response schema wiring look consistent.packages/go/openapi/src/paths/tasks.tasks.end.yaml (1)
17-48: LGTM — deprecated task end path is clearly documented.
Deprecation guidance and response schema wiring look consistent.packages/go/openapi/src/paths/tasks.tasks.id.yaml (1)
26-57: LGTM — clear deprecation guidance and response schema.packages/go/openapi/src/paths/tasks.tasks.id.cancel.yaml (1)
26-57: LGTM — deprecation note and response set are consistent.packages/go/openapi/src/paths/tasks.tasks.finished.yaml (1)
1-83: LGTM! Well-structured deprecated endpoint definition.The deprecation notice is clear with proper migration guidance to
GET /api/v2/jobs/finished. The response schema correctly usesallOfcomposition with the pagination envelope.One minor observation: This endpoint does not define a 404 response, whereas
tasks.tasks.yamldoes include one. This is likely intentional since a "list" endpoint returns an empty array rather than 404 when no items are found, so the current design is appropriate.packages/go/openapi/src/openapi.yaml (1)
694-712: Deprecated task endpoints properly wired.All 9 path references exist and follow the established pattern from the jobs endpoints. The Tasks tag is correctly registered in
x-tagGroupsunder the Enterprise Only section, ensuring these endpoints appear correctly in API documentation.packages/go/openapi/doc/openapi.json (12)
13833-13836: Clear deprecation notice for combo-nodeThe explicit deprecation description improves visibility in the explorer.
14518-14521: Deprecation guidance is explicitThe replacement endpoint reference is clear and user-facing.
14833-14836: Deprecation notice with migration path looks goodThe guidance to the jobs endpoint is concise and consistent.
15697-15821: /api/v2/tasks/available documented consistently as deprecatedParameters and response schema look aligned with the jobs equivalent.
15822-15959: /api/v2/tasks/finished deprecation metadata is consistentPagination and error responses are documented clearly.
15960-16081: /api/v2/tasks deprecation entry is clearSchema and error mappings are well defined.
16082-16130: /api/v2/tasks/current deprecation entry looks goodThe response shape is clear and concise.
16131-16179: /api/v2/tasks/start deprecation entry looks goodDeprecated flag and migration guidance are explicit.
16180-16228: /api/v2/tasks/end deprecation entry looks goodMetadata and responses are consistent with other task endpoints.
16229-16290: /api/v2/tasks/{task_id} deprecation entry is clearThe path parameter and response schema are documented cleanly.
16291-16352: /api/v2/tasks/{task_id}/cancel deprecation entry looks goodResponses and deprecation guidance are consistent.
16353-16416: /api/v2/tasks/{task_id}/log deprecation entry looks goodThe response schema is clear and aligns with the deprecated status.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
packages/go/openapi/src/paths/analysis.asset-groups.id.combo-node.yaml
Outdated
Show resolved
Hide resolved
packages/go/openapi/src/paths/clients.clients.id.completed-tasks.yaml
Outdated
Show resolved
Hide resolved
cami-specter
force-pushed
the
BED-3312-handle-deprecated-endpoints
branch
from
a3983f3 to
64ba384
Compare
|
LGTM |
Description
This PR handles deprecated endpoints as part of BED-3312. Some endpoints still exist in the codebase, but were not showing in the OpenAPI documentation. Now those are restored and/or marked with clear deprecation warnings.
Motivation and Context
Resolves BED-3312
Why is this change required? What problem does it solve?
There were several endpoints in various states of "deprecation". The changes standardize the deprecated endpoints and add clarity to the OpenAPI UI/API Explorer page.
How Has This Been Tested?
I tested this by running BHE/BHCE locally and previewing my changes in the API Explorer page.
Screenshots (optional):
Tasks endpoints:
Adding deprecation description:
Types of changes
Checklist:
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.