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

Harmonise operationIds in openapi.yaml

Closed
  • Is something wrong?
#312 2 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
Refactor
Clarity
Mostly clear
Activity status
Active
Tech stack
openapi
Domain
api

Research direction

Start with spec/openapi.yaml and compare the operationId table against the two proposed schemes. Resolve whether Scheme A or Scheme B is preferred, then apply that convention to the current specification while leaving archive/legacy_consumer_spec/ unchanged. Done means the selected naming scheme is consistent across the listed operations and its breaking impact before 1.0 is understood.

Written by the indexing model from the issue text.

Description

OpenAPI spec

Problem

operationId values in spec/openapi.yaml mix four different conventions. Since operationIds become method names in every generated client, this inconsistency is visible to all API consumers.

  • The Tea prefix appears in 7 of 30 operations (getTeaProductByUuid, queryTeaComponents) and is absent from the rest (getComponentReleaseById, getLatestArtifact).
  • The same kind of lookup is suffixed ByUuid for products and product releases but ById for components and component releases.
  • Component release is the unmarked default for collection operations (getLatestCollection, getCollectionsByReleaseId, getCollection), while the product side is qualified (getLatestCollectionForProductRelease, getCollectionsByProductReleaseId, getCollectionForProductRelease). Nothing in the paths justifies the asymmetry.
  • discoveryByTei is a noun rather than a verb and is inaccurate, since the endpoint also accepts purl.

Proposal

Two candidate schemes are shown below. Either one is acceptable; the point is to pick one and apply it everywhere.

Scheme A, parent-first. <verb><Parent><Child>[ByVersion]. No Tea prefix, no ById suffix on single-item lookups. Verbs: query for top-level searches, list for parent-scoped listings, get for a single item, download for content. Latest goes before the noun and ByVersion after it, as the artifact operations already do. (list could be replaced by get, since the plural noun already carries cardinality; the only cost is that getProductReleases and queryProductReleases then read almost the same.)

Scheme B, Spring Data style. <verb><Subject>By<Property>[And<Property>], as in Spring Data derived query methods: the subject names what is returned, the predicate after By names the path or query parameters used to select it. This is the convention the current getReleasesByProductId and getCleByProductReleaseId already follow. Cardinality is carried by the subject noun, not by the verb, so get is used throughout for reads and download for content.

Path Current A: parent-first B: Spring Data style
/products queryTeaProducts queryProducts getProductsByIdentifier
/product/{uuid} getTeaProductByUuid getProduct getProductByUuid
/product/{uuid}/releases getReleasesByProductId listProductReleases getReleasesByProductUuid
/product/{uuid}/cle getCleByProductId getProductCle getCleByProductUuid
/productReleases queryTeaProductReleases queryProductReleases getProductReleasesByIdentifier
/productRelease/{uuid} getTeaProductReleaseByUuid getProductRelease getProductReleaseByUuid
/productRelease/{uuid}/cle getCleByProductReleaseId getProductReleaseCle getCleByProductReleaseUuid
/productRelease/{uuid}/collections getCollectionsByProductReleaseId listProductReleaseCollections getCollectionsByProductReleaseUuid
/productRelease/{uuid}/collection/latest getLatestCollectionForProductRelease getLatestProductReleaseCollection getLatestCollectionByProductReleaseUuid
/productRelease/{uuid}/collection/{collectionVersion} getCollectionForProductRelease getProductReleaseCollectionByVersion getCollectionByProductReleaseUuidAndVersion
/components queryTeaComponents queryComponents getComponentsByIdentifier
/component/{uuid} getTeaComponentById getComponent getComponentByUuid
/component/{uuid}/releases getReleasesByComponentId listComponentReleases getReleasesByComponentUuid
/component/{uuid}/cle getCleByComponentId getComponentCle getCleByComponentUuid
/componentReleases queryTeaComponentReleases queryComponentReleases getComponentReleasesByIdentifier
/componentRelease/{uuid} getComponentReleaseById getComponentRelease getComponentReleaseByUuid
/componentRelease/{uuid}/cle getCleByComponentReleaseId getComponentReleaseCle getCleByComponentReleaseUuid
/componentRelease/{uuid}/collections getCollectionsByReleaseId listComponentReleaseCollections getCollectionsByComponentReleaseUuid
/componentRelease/{uuid}/collection/latest getLatestCollection getLatestComponentReleaseCollection getLatestCollectionByComponentReleaseUuid
/componentRelease/{uuid}/collection/{collectionVersion} getCollection getComponentReleaseCollectionByVersion getCollectionByComponentReleaseUuidAndVersion
/artifact/{uuid}/latest getLatestArtifact unchanged getLatestArtifactByUuid
/artifact/{uuid}/{artifactVersion} getArtifactByVersion unchanged getArtifactByUuidAndVersion
/artifact/{uuid}/latest/download downloadLatestArtifact unchanged downloadLatestArtifactByUuid
/artifact/{uuid}/{artifactVersion}/download downloadArtifactByVersion unchanged downloadArtifactByUuidAndVersion
/artifact/{uuid}/latest/signature/download downloadLatestArtifactSignature unchanged downloadLatestArtifactSignatureByUuid
/artifact/{uuid}/{artifactVersion}/signature/download downloadArtifactSignatureByVersion unchanged downloadArtifactSignatureByUuidAndVersion
/token requestToken unchanged unchanged
/discovery discoveryByTei discover discover

Trade-offs:

  • Scheme A changes 21 operationIds and leaves the artifact and token operations untouched. Names stay short.
  • Scheme B changes 27 operationIds, including all six artifact operations, and names grow long once two parameters are involved. In exchange every name states exactly which parameters select the result, and the style matches what half of the file already does.

Impact

Breaking for generated clients built from 0.x specs, since method names change. This should land before 1.0. The archived 0.2.0 spec under archive/legacy_consumer_spec/ keeps its current operationIds.

Dominant language
Shell
Stars
120
Forks
24
Avg merge
1d 6h
Merged PRs (30d)
67

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.