Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Drop `sortField` and `sortOrder`: they block static hosting and buy consumers little

Open
  • Is something wrong?
#324 12 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Domain
api, documentation

Research direction

Start by reviewing the query endpoints listed in the issue and the definitions of sortField, sortOrder, and the five sort-field-* parameters. Check issues #231, #253, #247, and #249 for the existing rationale. Done means the parameters are removed, each resource has the proposed documented order, and pageSize and pageToken remain supported.

Written by the indexing model from the issue text.

Description

Backlog Prio 2

Static hosting is what most open source projects have, and it is enough for most of the TEA specification.

Apart from the query endpoints (/discovery, /products, /productReleases, /components, /componentReleases) and /token, every endpoint returns a fixed JSON document per UUID. Those documents can be generated at release time and served by any web server, GitHub Pages included. I expect many open source projects to stop there. Running a compliant TEA server is a burden they have no reason to carry, so initial adoption would otherwise be limited to the companies that must place a product on the EU market and not reach their upstream.

The query endpoints can be pre-generated too, with a rewrite rule that turns

/componentReleases?idType=PURL&idValue=pkg%3Amaven%2Forg.apache.logging.log4j%2Flog4j-core

into a path such as /componentReleases/PURL/pkg%3Amaven%2Forg.apache.logging.log4j%2Flog4j-core.json. Pagination is not an obstacle: most projects have few enough releases and components to fit in one page, so the file holds everything and says hasNext: false. Such a server is not compliant to the letter, but it is compliant in practice because no client verifies the page size it asked for.

sortField and sortOrder are where this stops being reasonable. Pre-generating one answer per identifier query is a maintenance cost a project can accept. Pre-generating one answer per identifier query and per sort field and per direction is not: on the release endpoints that is six copies of every result, all containing the same rows. A static publisher will generate one order and ignore the parameters, and the spec gives it no way to say so, so a client that asked for sortOrder=desc silently gets the file's order.

What the parameters cost and give

  • For products, components and collections sortField has exactly one allowed value, so the parameter selects nothing. Its description for collections admits the tie-breaker "is redundant unless additional collection sort fields are added later".
  • For releases, sorting by version is "the server's documented string collation; semantic-version precedence is not implied". Two servers may order the same releases differently and both are correct, so a client cannot rely on the result anyway.
  • The tie-breaker and continuation rules from #253 exist to keep sorting stable across pages. An opaque pageToken already guarantees that on its own.
  • A consumer that wants a different order sorts the page it received.

Proposal

Remove sortField, sortOrder and the five sort-field-* parameters. Keep pageSize and pageToken. Fix one documented order per resource: name for products and components, version for collections, and for releases the newest first, which is what #247 asked for and what a consumer checking for updates expects. If sorting options are needed later, they can be added in a minor version without breaking anyone.

References: #231 (introduced the parameters), #253 (tie-breaker and continuation rules), #247 and #249 (review questions that led to those rules).

Dominant language
Shell
Stars
117
Forks
24
Avg merge
1d 5h
Merged PRs (30d)
59

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from CycloneDX/transparency-exchange-api

All issues in CycloneDX/transparency-exchange-api

Similar issues

More Shell/Bash issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.