Merge pull request #195 from taleodor/2025-09-TEA-improvements-post-merge

TEA Improvements Post Product-Component model merge - 2025-09

Author: stevespringett

spec/openapi.yaml

@@ -12,7 +12,7 @@ info:
   license:
     name: Apache 2.0
     url: https://github.com/CycloneDX/transparency-exchange-api/blob/main/LICENSE
-  version: 0.1.0-beta.1
+  version: 0.2.0-beta.2
 servers:
   - url: http://localhost/tea/v1
     description: Local development
@@ -52,15 +52,11 @@ paths:
           description: UUID of TEA Product in the TEA server
           schema:
             "$ref": "#/components/schemas/uuid"
+        - $ref: "#/components/parameters/page-offset"
+        - $ref: "#/components/parameters/page-size"
       responses:
         '200':
-          description: Requested Releases of TEA Product found and returned
-          content:
-            application/json:
-              schema:
-                type: array
-                items:
-                  "$ref": "#/components/schemas/productRelease"
+          $ref: "#/components/responses/paginated-product-release"
         '400':
           $ref: "#/components/responses/400-invalid-request"
         '404':
@@ -94,7 +90,7 @@ paths:
   /productReleases:
     get:
       description: Returns a list of TEA product releases. Note that multiple product releases may match.
-      operationId: getTeaProductReleaseByIdentifier
+      operationId: queryTeaProductReleases
       parameters:
         - $ref: "#/components/parameters/page-offset"
         - $ref: "#/components/parameters/page-size"
@@ -111,7 +107,7 @@ paths:
     get:
       description: Returns a list of TEA products. Note that multiple products may
         match.
-      operationId: getTeaProductByIdentifier
+      operationId: queryTeaProducts
       parameters:
         - $ref: "#/components/parameters/page-offset"
         - $ref: "#/components/parameters/page-size"
@@ -174,15 +170,39 @@ paths:
           $ref: "#/components/responses/404-object-by-id-not-found"
       tags:
         - TEA Component
-  /release/{uuid}/collection/latest:
+  /componentRelease/{uuid}:
+    get:
+      description: Get the TEA Component Release with its latest collection
+      operationId: getComponentReleaseById
+      parameters:
+        - name: uuid
+          in: path
+          required: true
+          description: UUID of TEA Component Release in the TEA server
+          schema:
+            "$ref": "#/components/schemas/uuid"
+      responses:
+        '200':
+          description: Requested TEA Component Release and its latest Collection found and returned
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/component-release-with-collection"
+        '400':
+          $ref: "#/components/responses/400-invalid-request"
+        '404':
+          $ref: "#/components/responses/404-object-by-id-not-found"
+      tags:
+        - TEA Component Release        
+  /componentRelease/{uuid}/collection/latest:
     get:
-      description: Get the latest TEA Collection belonging to the TEA Release
+      description: Get the latest TEA Collection belonging to the TEA Component Release
       operationId: getLatestCollection
       parameters:
         - name: uuid
           in: path
           required: true
-          description: UUID of TEA Release in the TEA server
+          description: UUID of TEA Component Release in the TEA server
           schema:
             "$ref": "#/components/schemas/uuid"
       responses:
@@ -197,7 +217,7 @@ paths:
         '404':
           $ref: "#/components/responses/404-object-by-id-not-found"
       tags:
-        - TEA Release
+        - TEA Component Release
   /productRelease/{uuid}/collection/latest:
     get:
       description: Get the latest TEA Collection belonging to the TEA Product Release
@@ -222,15 +242,15 @@ paths:
           $ref: "#/components/responses/404-object-by-id-not-found"
       tags:
         - TEA Product Release
-  /release/{uuid}/collections:
+  /componentRelease/{uuid}/collections:
     get:
-      description: Get the TEA Collections belonging to the TEA Release
+      description: Get the TEA Collections belonging to the TEA Component Release
       operationId: getCollectionsByReleaseId
       parameters:
         - name: uuid
           in: path
           required: true
-          description: UUID of TEA Release in the TEA server
+          description: UUID of TEA Component Release in the TEA server
           schema:
             "$ref": "#/components/schemas/uuid"
       responses:
@@ -247,7 +267,7 @@ paths:
         '404':
           $ref: "#/components/responses/404-object-by-id-not-found"
       tags:
-        - TEA Release
+        - TEA Component Release
   /productRelease/{uuid}/collections:
     get:
       description: Get the TEA Collections belonging to the TEA Product Release
@@ -282,7 +302,7 @@ paths:
         - name: uuid
           in: path
           required: true
-          description: UUID of TEA Release in the TEA server
+          description: UUID of TEA Product Release in the TEA server
           schema:
             "$ref": "#/components/schemas/uuid"
         - name: collectionVersion
@@ -304,9 +324,9 @@ paths:
           $ref: "#/components/responses/404-object-by-id-not-found"
       tags:
         - TEA Product Release
-  /release/{uuid}/collection/{collectionVersion}:
+  /componentRelease/{uuid}/collection/{collectionVersion}:
     get:
-      description: Get a specific Collection (by version) for a TEA Release by its UUID
+      description: Get a specific Collection (by version) for a TEA Component Release by its UUID
       operationId: getCollection
       parameters:
         - name: uuid
@@ -333,7 +353,7 @@ paths:
         '404':
           $ref: "#/components/responses/404-object-by-id-not-found"
       tags:
-        - TEA Release
+        - TEA Component Release
   /artifact/{uuid}:
     get:
       description: Get metadata for specific TEA artifact
@@ -436,6 +456,10 @@ components:
         product:
           description: UUID of the TEA Product this release belongs to
           "$ref": "#/components/schemas/uuid"
+        productName:
+          description: Name of the TEA Product this release belongs to
+          type: string
+          example: Apache Log4j 2
         version:
           description: Version number of the product release
           type: string
@@ -542,7 +566,7 @@ components:
 
 
     #
-    # TEA Release and related objects
+    # TEA Component Release and related objects
     #
     release:
       type: object
@@ -554,6 +578,10 @@ components:
         component:
           description: UUID of the TEA Component this release belongs to
           "$ref": "#/components/schemas/uuid"
+        componentName:
+          description: Name of the TEA Component this release belongs to
+          type: string
+          example: tomcat
         version:
           description: Version number
           type: string
@@ -707,6 +735,57 @@ components:
           url: https://dlcdn.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe
           signatureUrl: https://downloads.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe.asc
 
+    component-release-with-collection:
+      type: object
+      description: A TEA Component Release combined with its latest collection
+      properties:
+        release:
+          description: The TEA Component Release information
+          $ref: "#/components/schemas/release"
+        latestCollection:
+          description: The latest TEA Collection for this component release
+          $ref: "#/components/schemas/collection"
+      required:
+        - release
+        - latestCollection
+      examples:
+        - release:
+            uuid: 605d0ecb-1057-40e4-9abf-c400b10f0345
+            version: "11.0.7"
+            createdDate: 2025-05-07T18:08:00Z
+            releaseDate: 2025-05-12T18:08:00Z
+            identifiers:
+              - idType: PURL
+                idValue: pkg:maven/org.apache.tomcat/[email protected]
+          latestCollection:
+            uuid: 605d0ecb-1057-40e4-9abf-c400b10f0345
+            version: 2
+            date: 2025-05-12T18:08:00Z
+            belongsTo: COMPONENT_RELEASE
+            updateReason:
+              type: INITIAL_RELEASE
+              comment: Initial collection for this release
+            artifacts:
+              - uuid: 1cb47b95-8bf8-3bad-a5a4-0d54d86e10ce
+                name: Build SBOM
+                type: BOM
+                formats:
+                  - mimeType: application/vnd.cyclonedx+xml
+                    description: CycloneDX SBOM (XML)
+                    url: https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.7-cyclonedx.xml
+                    checksums:
+                      - algType: SHA-256
+                        algValue: 9da736a1cdd27231e70187cbc67398d29ca0b714f885e7032da9f1fb247693c1
+              - uuid: dfa35519-9734-4259-bba1-3e825cf4be06
+                name: Vulnerability Disclosure Report
+                type: VULNERABILITIES
+                formats:
+                  - mimeType: application/vnd.cyclonedx+xml
+                    description: CycloneDX VDR (XML)
+                    url: https://tomcat.apache.org/cyclonedx/vdr.xml
+                    checksums:
+                      - algType: SHA-256
+                        algValue: 75b81020b3917cb682b1a7605ade431e062f7a4c01a412f0b87543b6e995ad2a
 
     #
     # TEA Collection and related objects
@@ -797,7 +876,7 @@ components:
       type: string
       description: Indicates whether a collection belongs to a component release or a product release
       enum:
-        - RELEASE
+        - COMPONENT_RELEASE
         - PRODUCT_RELEASE
 
     #
@@ -921,6 +1000,30 @@ components:
         - pageStartIndex
         - pageSize
         - totalResults
+    
+    paginated-product-response:
+      type: object
+      description: A paginated response containing TEA Products
+      allOf:
+        - $ref: "#/components/schemas/pagination-details"
+        - type: object
+          properties:
+            results:
+              type: array
+              items:
+                $ref: "#/components/schemas/product"
+    
+    paginated-product-release-response:
+      type: object
+      description: A paginated response containing TEA Product Releases
+      allOf:
+        - $ref: "#/components/schemas/pagination-details"
+        - type: object
+          properties:
+            results:
+              type: array
+              items:
+                $ref: "#/components/schemas/productRelease"
   responses:
     204-common-delete:
       description: Object deleted successfully
@@ -943,27 +1046,13 @@ components:
       content:
         application/json:
           schema:
-            allOf:
-              - $ref: "#/components/schemas/pagination-details"
-              - type: object
-                properties:
-                  results:
-                    type: array
-                    items:
-                      "$ref": "#/components/schemas/product"
+            $ref: "#/components/schemas/paginated-product-response"
     paginated-product-release:
       description: A paginated response containing TEA Product Releases
       content:
         application/json:
           schema:
-            allOf:
-              - $ref: "#/components/schemas/pagination-details"
-              - type: object
-                properties:
-                  results:
-                    type: array
-                    items:
-                      "$ref": "#/components/schemas/productRelease"
+            $ref: "#/components/schemas/paginated-product-release-response"
   parameters:
     # Pagination
     page-offset:
@@ -1037,7 +1126,7 @@ tags:
   - name: TEA Product
   - name: TEA Product Release
   - name: TEA Component
-  - name: TEA Release
+  - name: TEA Component Release
   - name: TEA Artifact
 externalDocs:
   description: Transparency Exchange API specification