CycloneDX / CycloneDX/transparency-exchange-api

Expand error-response coverage for 406, signatures, /token 404, and 400/204 cleanup

Open
#285 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Shell
Stars
113
Forks
22
Avg merge
8d 12h
Merged PRs (30d)
5

Description

## Summary

Several documented HTTP outcomes cannot be expressed accurately with the current `error-response` model. `unknown-error-type` only allows `OBJECT_UNKNOWN` and `OBJECT_NOT_SHAREABLE`, but download flows also need to signal “no matching format” and “no signature,” `/token` documents an unimplemented-endpoint `404` that OpenAPI does not declare, generic `400` bodies are unspecified, and an unused body-bearing `204` component remains in the spec.

#270 improves concealment (`403` vs concealing `404`) but does not close these gaps. This issue tracks the remaining error-coverage work as a follow-up after #270 merges.

## Current gaps

### 1. `406` cannot name “format unavailable”
Download operations declare `406` via `406-no-acceptable-format`, whose body is `error-response` → `unknown-error-type`. That enum only has:
- `OBJECT_UNKNOWN`
- `OBJECT_NOT_SHAREABLE`

Neither means “the revision exists but no format matches `mediaType` / `Accept`.”

### 2. Missing signature uses a generic `404`
Artifact signature download prose returns `404` when the selected format has no published signature, but the response is the same `404-object-by-id-not-found` / object-unknown path used for missing resources. Clients cannot distinguish “artifact unknown” from “signature not published.”

### 3. `/token` `404` is documented but not in OpenAPI
`/token` description says a `404` means the endpoint is not implemented (open / no-auth servers). Declared responses are only `200` / `400` / `401`. The operation table in published docs therefore omits a documented outcome.

### 4. Generic `400` body is unspecified
`400-invalid-request` uses `application/json: {}` with no schema. Either define a common structured body, or state explicitly that clients must not depend on `400` contents (token errors already have `token-error-response`).

### 5. Unused `204-common-delete`
`components.responses.204-common-delete` declares JSON content on a bodyless `204`, and nothing `$ref`s it. It should be removed or corrected if delete is ever in scope.

## Proposed direction

- Extend `unknown-error-type` (or split error enums by context) with distinct codes such as:
- `NO_ACCEPTABLE_FORMAT` for `406`
- `SIGNATURE_NOT_FOUND` for signature-absent `404`
- Keep concealment semantics from #270: concealing `404` remains `OBJECT_UNKNOWN` / not-shareable as already described there — do not overload those for format/signature cases.
- Declare `404` on `/token` with a clear description (not implemented), distinct from resource `404-object-by-id-not-found`.
- For resource `400-invalid-request`: either a small shared schema or an explicit “body not interoperable / do not depend on contents” rule.
- Remove unused `204-common-delete` (or fix it if retained).

## Relation to other work

- **#270 / #269:** concealment and `401`/`403` — prerequisite; land first, then implement this.
- **#274:** discovery `404` overload (TEI unknown vs endpoint missing) — related theme, separate issue; this issue is about OpenAPI error *bodies* and download/`/token` coverage.
- **#272 / #277:** token cache/encoding and RFC 8693 deferral — do not cover these gaps.

## Out of scope

- Redesigning pagination `400` semantics beyond stating body policy
- Publisher/delete API surface (unless `204-common-delete` is intentionally revived)
- CLE or discovery cardinality response shape

If this direction looks right I'll make a PR after #270 merge?

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.