CycloneDX / CycloneDX/transparency-exchange-api
Clarify discovery cardinality, response array, and direct PURL lookup
- Dominant language
- Shell
- Stars
- 113
- Forks
- 22
- Avg merge
- 8d 12h
- Merged PRs (30d)
- 5
Description
## Summary
Discovery prose and OpenAPI disagree on how many product releases a TEI can resolve to. The discovery document also does not describe the actual success response shape, and it never documented the direct-PURL workflow that #265 added to OpenAPI (“spec only; documentation unchanged”).
## Current gaps
- `discovery/readme.md` says a TEI belongs to a single product release, then later allows the same identifier (e.g. EAN) to span multiple releases.
- Successful `/discovery` is not described as the OpenAPI array of `discovery-info` objects (`productReleaseUuid` + `servers[]`).
- OpenAPI allows `200` with an empty array; a no-match should be `404`.
- Direct `purl=` lookup (already-known API base; exactly one of `tei`/`purl`) is in OpenAPI but missing from the discovery narrative.
- `.well-known` endpoint list vs `servers[].rootUrl` should be explicitly related.
## Proposed direction
- A TEI MAY resolve to multiple product releases; vendors SHOULD prefer one.
- Successful lookup MUST return a non-empty array of `discovery-info`; no match MUST return `404` (not `200` + `[]`).
- Add `minItems: 1` on the discovery response array; document `productReleaseUuid` + `servers[]`.
- Document direct PURL discovery as requiring an already-known API endpoint.
This is consistent with the direction discussed in #274: on a conforming `/discovery` handler, 404 means the identifier is unknown (not “empty success”). #274 can stay focused on overloaded 404 / failover wording; this issue is about cardinality, response shape, and the #265 docs gap.
## My Question
Does this direction look right for a follow-up PR I'd put together?
Contributor guide
Research direction
Start with discovery/readme.md and the existing OpenAPI discovery definitions, comparing their cardinality, response shape, status codes, direct-purl workflow, and endpoint relationships. Update the documentation and schema so the narrative matches the proposed behavior, including a non-empty discovery-info array and 404 for no match; done means the stated gaps are consistent across both sources.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 75/100