Add an OpenAPI-based RDX REST API profile with JSON Patch/merge semantics

[github-actions]

Motivation

RDX is used both as standalone documents and embedded inside CycloneDX BOMs (RDX-036..039, RDX-099). Many consumers and orchestration systems would benefit from a standardized, server-oriented interchange pattern: a minimal REST API (OpenAPI 3.1) for publishing, querying, and incrementally updating RDX documents. Standardizing an API avoids ad-hoc endpoints, enables tool vendors to interoperate, and supports partial updates for large TARAs without re-uploading full documents.

Key capabilities: CRUD for RDX documents, query/filter by itemDefinition/documentId/createdBy, partial updates using RFC 6902 (JSON Patch) or RFC 7396 (JSON Merge Patch), strong versioning and ETag concurrency, and optional pagination for large riskSets.

Proposed change

1. New artifact: spec/api/rdx-openapi.yaml (OpenAPI 3.1) describing a REST profile with the following endpoints (all JSON media types):

   • POST /rdx/documents — create RDX document (accepts full RDX JSON). Response includes documentId and location.
   • GET /rdx/documents/{documentId} — fetch full RDX document (support query param embedCycloneDX=true|false).
   • GET /rdx/documents?itemId={id}&createdBy={actor}&since={date} — filter listing (supports pagination).
   • PATCH /rdx/documents/{documentId} — partial update. Support Content-Type: application/json-patch+json (RFC 6902) and application/merge-patch+json (RFC 7396). The OpenAPI schema SHALL document patchable paths (e.g., riskSet.attackPaths, controls[], relationships[]) and describe idempotency/ordering semantics for array edits (patch best-practices).
   • PUT /rdx/documents/{documentId}/versions — append a new version (full document) to implement version history.
   • DELETE /rdx/documents/{documentId} — delete or mark-retired (soft-delete with reason).
   • HEAD /rdx/documents/{documentId} — return headers (ETag, last-modified, schemaVersion).

2. Server contract details in spec/api/rdx-openapi.yaml:

   • ETag-based optimistic concurrency (ETag required on PATCH/PUT; server MUST return 412 Precondition Failed if mismatch).
   • Support If-Match / If-None-Match semantics for safe updates.
   • Pagination headers (RFC 8288 style) and Link for next/prev.
   • Response codes documented and machine-friendly error model (problem+json format).

3. Add tools/api/mock_server/ reference server (Node.js/Express or Python/Flask) that implements the OpenAPI contract and demonstrates JSON Patch application to an example RDX document. Include tests exercising concurrency (ETag) and patch semantics.

4. Update docs in methodology/ describing how to embed CycloneDX-embedded RDX in the REST API responses and how consumers should handle large embedded CycloneDX BOMs (support Content-Encoding and chunking guidance).

5. New requirement in REQUIREMENTS.md: RDX-121: "Provide a standard OpenAPI REST profile for RDX document CRUD and partial updates using RFC 6902/7396 semantics" (new requirement).

Backward-compatible: this is an API profile and tooling; it does not change on-disk schemas.

References

• OWASP / CycloneDX BOM Exchange API and related REST approaches. https://cyclonedx.org/news/owasp-cyclonedx-launches-sbom-exchange-api--standardizing-sbom-distribution/.
• CycloneDX sbom-utility (example API platform for BOMs). https://github.com/CycloneDX/sbom-utility.
• RFC 6902 JSON Patch (partial update operations). https://datatracker.ietf.org/doc/html/rfc6902.
• RFC 7396 JSON Merge Patch (simple partial update). https://datatracker.ietf.org/doc/html/rfc7396.

Acceptance criteria

1. Add spec/api/rdx-openapi.yaml OpenAPI 3.1 file describing endpoints above, example requests/responses, security scheme (bearer token) and pagination.
2. Add tools/api/mock_server/ minimal reference server implementing create/get/patch semantics and a test suite that runs the following scenarios:
   • Create an RDX document and receive documentId.
   • Apply a JSON Patch that updates an attackPath step and verify other fields are untouched.
   • Attempt concurrent PATCH with stale ETag and receive 412.
   • Retrieve paginated listing for documents filtered by itemDefinition id.
3. Document in methodology/API.md guidance about embedding CycloneDX content, payload size recommendations, and recommended Content-Type headers.
4. Update REQUIREMENTS.md with RDX-121 (new requirement), and add a short conformance checklist for server implementers (ETag support, support for both RFC6902 and RFC7396 content types, error model).
5. CI job to run mock_server tests on PRs touching spec or tooling files.

---

Generated by tools/ai_idea_scout.py via the AI Idea Scout workflow.
Review the proposal, refine the title/body/labels, and close if not desired.