Artifact download: let HTTP do the rest
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 30/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Active
- Domain
- api, backend-api-design
Research direction
Start by reading the endpoint proposal in #262, the encoding issue in #283, and the artifact-format material discussed here. Work through the HTTP negotiation, signature-link, checksum, and artifact representation changes; done means the specification consistently defines one revision download endpoint plus its latest alias without the duplicated transport fields.
Written by the indexing model from the issue text.
Description
The download endpoint from #262 is a great move. /artifact/{uuid}/{artifactVersion}/download is something you can curl: no TEA client library, no metadata parsing, and content negotiation, ETag, Cache-Control and Repr-Digest all come from HTTP for free. Thanks for that.
I think it can be taken one step further. Once the endpoint exists, most of what artifact-format describes is already expressed by HTTP:
- Format selection is
Accept. ThemediaTypequery parameter duplicates it, with its own matching and encoding rules (see #283). Dropping the parameter leaves what every framework already implements:Acceptin,Content-TypeandVary: Acceptout,406when nothing matches. artifact-formatreduces to a list of media types. With negotiation on the endpoint, an artifact needs at most to advertise which media types it is available in. The per-format sub-object withurl,signatureUrl,checksumsanddescriptionis no longer needed.- Direct download URLs are not needed. The endpoint already answers
302to an external location. That covers pre-signed object storage, Maven Central and everything elseurlwas for, and the token boundary is simply "under the API base or not". - The signature is a link on the response. An RFC 8288
Linkheader with a TEA relation type, for exampleLink: <…>; rel="https://tc54.org/tea/rel/signature", names the signature of exactly the representation returned, onGETandHEAD. There is no registered relation for detached signatures (the closest precedent in the IANA registry isc2pa-manifest), and RFC 8288 allows a URI, so nothing needs registering. No signature endpoint family, nomediaTypeparameter on it, noSIGNATURE_NOT_FOUND: no link means no signature. - Checksums are already there.
Repr-Digest(RFC 9530) is defined on the download response. It can be the only place checksums live, and it coversHEADtoo.
The result is one endpoint per artifact revision, plus its latest alias, and an artifact object that lists media types instead of describing transports. Everything else is standard HTTP that clients and servers already have.
References: #246 (motivation), #262 (the endpoint), #283 (encoding issue caused by the mediaType parameter).
- Dominant language
- Shell
- Stars
- 116
- Forks
- 23
- Avg merge
- 2d 11h
- Merged PRs (30d)
- 63
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from CycloneDX/transparency-exchange-api
-
align on terminology Open
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
CycloneDX/transparency-exchange-api#393 · 1 comment ·
-
TEI Discovery
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
TEI Discovery
Difficulty 1/5 Under an hour Newbie friendliness 90/100
-
TEI Discovery
Difficulty 1/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
All issues in CycloneDX/transparency-exchange-api
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 1/5 Under an hour Newbie friendliness 92/100
uttrflow/uttrflow-swift#1439 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
msys2/MINGW-packages#31930 ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 72/100