feat: This is a simplification of the Consumer API Spec #180

madpah · 2025-05-30T19:00:06Z

This is draft PR that follows the Slack discussions here and here - supported by the attached Zoom Whiteboard (also here) where @nscuro and myself considered, from the Consumer perspective a simplification whilst also consider (as discussed during OWASP Hackathon) the necessary support for Product Versioning.

Revised API Flow (Main Flow)

sequenceDiagram
    actor Client
    Client->>TEA Service: POST /product/search with TEI
    TEA Service-->>Client: TEA Product returned
    Note over TEA Service: This includes a list of TEA Collection identifiers

    loop For every TEA Collection identifier
    Client->>TEA Service: GET /collection/{id}/latest
    TEA Service-->>Client: TEA Collection returned
    Note over TEA Service: This includes all TEA Artifacts in the TEA Collection
    end

References / Workings

Revised simplified data model suggestion (data model, not API Spec):

Worked examples:

FYI @stevespringett

Signed-off-by: Paul Horton <[email protected]>

taleodor · 2025-05-30T19:23:13Z

There are great ideas here, but I feel like the logic breaks when we try to define the concepts of "unversioned product" and "latest versions of components".

Observe that:

A set of components may change between product releases (say, we dropped, added or replaced an upstream component)
"Latest" release is frequently not clearly defined, i.e. may a "pre-release" be considered latest?
Let's assume we defined "Latest" - this would imply that we still need binding for all Component Releases to be able to select the "Latest" among them. That means that the "Component" object entity is still present, just hidden in the model. Of course, we may let implementations work this out, but if this is already clear that the "Component" entity must exist in any case, why not have that added explicitly to the spec? Similar reasoning can be applied to "Product" -> "Product Releases" relationship.

If we respect these limitation, this will actually become very close to the existing spec with certain updates. Particularly, what I really like about this PR is "/product/search" POST call. However, I don't think it's a replacement for /product/{uuid} due to limitations mentioned above.

ppkarwasz

Hi @madpah,

Thanks for sharing this! I think this PR has the potential to simplify TEA nicely. Even if it’s still an early draft, I wanted to highlight a few concerns and questions I have about the proposed changes.

ppkarwasz · 2025-05-31T18:19:10Z

spec/openapi.yaml

+  /product/search:
+    post:


I assume this change addresses the concerns in #159 about percent-encoding the TEI in the URL path.

Switching to POST simplifies clients but prevents deploying a TEA service on static web servers like GitHub Pages, which can only serve GET requests. I'd like to see TEA work across the full spectrum—from static sites to dynamic services. Using only GET with path parameters for the most important endpoints could help preserve that flexibility.

@ppkarwasz The working group should make a decision as to whether such static deployments must be supported. IMO, it would heavily limit what the API can offer and express.

Some parts of the API certainly could require a dynamically generated response. For example /products require such a response, unless you totally ignore all query parameters.

However, I believe that dynamic endpoints should be used sparingly, when there is no alternative. In this case the alternative is clear: the TEI can be properly encoded and passed as path parameter.

ppkarwasz · 2025-05-31T19:11:12Z

spec/openapi.yaml

+      examples:
+        - urn:tei:ean:philips-hue.com:8719514329928
+        - urn:tei:hash:cyclonedx.org:SHA256:fd44efd601f651c8865acf0dfeacb0df19a2b50ec69ead0262096fd2f67197b9
+        - urn:tei:purl:cyclonedx.org:pkg:pypi/[email protected]?extension=whl&qualifier=py3-none-any


Suggested change

- urn:tei:purl:cyclonedx.org:pkg:pypi/[email protected]?extension=whl&qualifier=py3-none-any

- urn:tei:purl:cyclonedx.org:pkg:pypi/[email protected]%3Fextension=whl&qualifier=py3-none-any

RFC 8141 does not allow ? to appear unencoded in an NSS.

ppkarwasz · 2025-05-31T19:18:18Z

spec/openapi.yaml

+           description: TEA Product found and returned
+           content:
            application/json:
              schema:
-                $ref: "#/components/schemas/product"
+                "$ref": "#/components/schemas/product"


Which version of the product object should be returned by this query?

Should it be the latest one? If so, can we retrieve other version of the TEA Product?

Refer to the screenshots @madpah added to the PR description. Searching by a TEI without version qualifier returns the latest version, whereas searching with version qualifier yields that specific version:

ppkarwasz · 2025-05-31T19:22:25Z

spec/openapi.yaml

        - uuid: 09e8c73b-ac45-4475-acac-33e6a7314e6d
          name: Apache Log4j 2
+          version: 2.12.0
+          createdAt: 2017-07-21T17:32:28.003Z
+          preRelease: false
          identifiers:
            - idType: CPE
-              idValue: cpe:2.3:a:apache:log4j
+              idValue: cpe:2.3:a:apache:log4j:2.12.0
            - idType: PURL
-              idValue: pkg:maven/org.apache.logging.log4j/log4j-api
+              idValue: pkg:maven/org.apache.logging.log4j/log4j-api@2.12.0
            - idType: PURL
-              idValue: pkg:maven/org.apache.logging.log4j/log4j-core
+              idValue: pkg:maven/org.apache.logging.log4j/log4j-core@2.12.0
            - idType: PURL
-              idValue: pkg:maven/org.apache.logging.log4j/log4j-layout-template-json
+              idValue: pkg:maven/org.apache.logging.log4j/log4j-layout-template-json@2.12.0


Nitpick: in previous conversations it was pointed out that these PURLs do not belong to the TEA Product, but the TEA Components. Could your remove them?

These PURLs do not point to the entire product, but only part of it.

ppkarwasz · 2025-05-31T19:23:55Z

spec/openapi.yaml

-        identifiers:
-          type: array
-          description: List of identifiers for the component
-          items:
-            "$ref": "#/components/schemas/identifier"


Identifiers specific to a single TEA Component could be stored in the component object.

ppkarwasz · 2025-05-31T19:25:02Z

spec/openapi.yaml

+        3. Philips Hue Bulb
+
+        It is also permissible for a TEA Component to also be a TEA Product by also creating a 
+        separate TEA Product that refers to same TEA Component.
      properties:
        uuid:


Nitpick: you didn't rename component.uuid to component.id.

ppkarwasz · 2025-05-31T19:55:30Z

spec/openapi.yaml

+  /component/{id}:
    get:
-      description: Get a TEA Component
+      description: Get a TEA Component by it's Identifier


The semantics of the id in /component/{id} are unclear:

If multiple component versions share the same id, which version does this endpoint return?

If each component version has a unique id, how can clients retrieve all versions of a given component?

If multiple component versions share the same id, which version does this endpoint return?

With the idea being to collapse the logical models of Component and Component Release, id would always refer to a specific component version.

If each component version has a unique id, how can clients retrieve all versions of a given component?

What is the use case for listing all versions of a component? tea-usecases.md doesn't seem to have any.

If you're referring to use case D1, that use case will need a separate discovery mechanism anyway, and would work just as well if all component versions are distinct records.

There was an issue about discovering new versions of a component (#36).

nscuro · 2025-06-04T11:03:24Z

@taleodor "Latest" release is frequently not clearly defined, i.e. may a "pre-release" be considered latest?

I would suggest to not try to infer "latest" somehow - this is bound to fail due to the various ambiguities in versioning and release patterns. Instead, let's let publishers explicitly define what version is "latest". This mirrors what you can do in GitHub Releases, and FWIW, it's a mechanism that DT has adopted as well.

@taleodor Let's assume we defined "Latest" - this would imply that we still need binding for all Component Releases to be able to select the "Latest" among them. [...] Similar reasoning can be applied to "Product" -> "Product Releases" relationship.

Possibly. Excuse my ignorance, and this is likely because I joined the effort so late, but where does the need to determine the "latest" component release stem from?

Are we trying to mix transparency artifact exchange with generalized component (version) discovery? Doesn't it suffice for TEA to track component versions as-is?

I get the need for this on the product level, but components?

taleodor · 2025-06-04T11:33:27Z

@nscuro

I would suggest to not try to infer "latest" somehow - this is bound to fail due to the various ambiguities in versioning and release patterns. Instead, let's let publishers explicitly define what version is "latest". This mirrors what you can do in GitHub Releases, and FWIW, it's a mechanism that DT has adopted as well.

GitHub Releases has no concept of latest, I demonstrated this on one of the calls, can repeat today. Essentially, it may have releases from different streams all mashed together without clear order. Similarly, for DT, it's just a flag, but sometimes it's not meaningful. I.e., a project supports 2 major or minor versions (in semver) at the same time, each of them has their own latest.

Possibly. Excuse my ignorance, and this is likely because I joined the effort so late, but where does the need to determine the "latest" component release stem from?

Component is an upstream dependency of Product. If there is a newer Component Release, as a developer / DevSecOps, I would like to migrate to that, especially if it has security updates.

So the full example is like this -

I'm using library ACMElib v.1.1.0
I want to know if there is a newer version available
ACMElib just released v.1.1.1 (which is a security patch for v.1.1.0), as well as v.1.2.0 (which is a new feature release).
I want TEA to inform me that v.1.1.1 is the one I can immediately upgrade to, while 1.2.0 is also there, but requires more testing since it's a feature update.

nscuro · 2025-06-04T12:05:23Z

GitHub Releases has no concept of latest, I demonstrated this on one of the calls, can repeat today. Essentially, it may have releases from different streams all mashed together without clear order. Similarly, for DT, it's just a flag, but sometimes it's not meaningful.

Oh, I'm fully with you on that. It's not perfect, but it's one of those things that are "good enough" for most applications. It is more akin to "latest and greatest", instead of "latest of stream XYZ".

I.e., a project supports 2 major or minor versions (in semver) at the same time, each of them has their own latest.

What I have seen from TEA so far would also not cater to this (I may just have missed it). Are you arguing against having the concept of "latest" altogether? I think that would drastically simplify things.

If there is a newer Component Release, as a developer / DevSecOps, I would like to migrate to that, especially if it has security updates.

I would challenge if that is a use case TEA should cater to. There is already a vast array of tooling out there that informs about (and performs) version updates. A good chunk of versioning logic is different in each ecosystem, and even within those the rules are not always clear and fully enforced. IMO, TEA should act as a supplement to those (i.e. lookup more info about versions you're considering updating to).

I feel this inflates the TEA spec and deviates from it's primary goal (the exchange), but I respect if this is a direction the WG has decided TEA should go.

taleodor · 2025-06-04T12:21:18Z

What I have seen from TEA so far would also not cater to this (I may just have missed it). Are you arguing against having the concept of "latest" altogether? I think that would drastically simplify things.

Yes, I don't think we should have the concept of latest. Container images supported it and it almost immediately became an anti-pattern. Instead, I believe we should keep the split between Component and Component Release and Product and Product Release. Then the API consumer would have options what to do with that (similar to the existing GitHub Releases workflow).

In the practical sense of this PR, it means that if a user searches for TEI without version, this leads to a Product that lists all available versions and not to some latest version. And it should work the same way for Components. Products and Components are not that different.

I would challenge if that is a use case TEA should cater to. There is already a vast array of tooling out there that informs about (and performs) version updates.

The novelty here is that TEA would have publisher supplying these data in a structured format. My understanding is that existing tooling should use publisher's TEA to make decisions rather than 3rd party heuristics. This is something that is better to discuss on the call though for establishing common approach.

nscuro · 2025-06-04T12:25:53Z

In the practical sense of this PR, it means that if a user searches for TEI without version, this leads to a Product that lists all available versions and not to some latest version. And it should work the same way for Components. Products and Components are not that different.

Pragmatic, I like it.

Edit: I think the intention behind returning the "latest" version for a TEI without version is specifically for cases where a product doesn't really have a version. But I guess using a pseudo-version for such products would work just as well.

My understanding is that existing tooling should use publisher's TEA to make decisions rather than 3rd party heuristics.

If this is a goal then we should document it. I fear the tea-usecases.md doc may be horribly outdated at this point.

feat: This is a simplification of the Consumer API Spec

94562c2

Signed-off-by: Paul Horton <[email protected]>

madpah added OpenAPI spec hackathon Raised during OWASP Hackathon labels May 30, 2025

madpah self-assigned this May 30, 2025

feat: This is a simplification of the Consumer API Spec

31facf6

Signed-off-by: Paul Horton <[email protected]>

ppkarwasz suggested changes May 31, 2025

View reviewed changes

	- urn:tei:purl:cyclonedx.org:pkg:pypi/[email protected]?extension=whl&qualifier=py3-none-any
	- urn:tei:purl:cyclonedx.org:pkg:pypi/[email protected]%3Fextension=whl&qualifier=py3-none-any

Uh oh!

feat: This is a simplification of the Consumer API Spec #180

Are you sure you want to change the base?

feat: This is a simplification of the Consumer API Spec #180

Uh oh!

Conversation

madpah commented May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Revised API Flow (Main Flow)

References / Workings

Uh oh!

taleodor commented May 30, 2025

Uh oh!

ppkarwasz left a comment

Choose a reason for hiding this comment

Uh oh!

ppkarwasz May 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nscuro commented Jun 4, 2025

Uh oh!

taleodor commented Jun 4, 2025

Uh oh!

nscuro commented Jun 4, 2025

Uh oh!

taleodor commented Jun 4, 2025

Uh oh!

nscuro commented Jun 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

madpah commented May 30, 2025 •

edited

Loading

ppkarwasz May 31, 2025 •

edited

Loading

nscuro commented Jun 4, 2025 •

edited

Loading