Skip to content

Commit cabb23e

Browse files
madpahmadpah
authored
Merge pull request CycloneDX#77 from vpetersson/main
Tweak OpenAPI specs and workflows
2 parents 1c1c949 + b4db432 commit cabb23e

File tree

5 files changed

+1053
-208
lines changed

5 files changed

+1053
-208
lines changed

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
.idea/
2-
out/*
2+
out/*
3+
.DS_Store

‎api-flow/consumer.md‎

Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# Transparency Exchange API: Consumer access
22

33

4-
The consumer access starts with a TEI, A transparency Exchange Identifier. This is used to find the API server as
4+
The consumer access starts with a TEI, A transparency Exchange Identifier. This is used to find the API server as
55
described in the [discovery document](/discovery/readme.md).
66

77
## API usage
@@ -27,25 +27,26 @@ sequenceDiagram
2727
autonumber
2828
actor user
2929
participant discovery as TEA Discovery with TEI
30-
box LightGrey TEA API service
31-
participant teaindex as TEA Index
32-
end
33-
34-
30+
31+
participant tea_product as TEA Product
32+
participant tea_leaf as TEA Leaf
33+
participant tea_collection as TEA Collection
34+
participant tea_artifact as TEA Artefact
35+
3536
3637
user ->> discovery: Discovery using DNS
3738
discovery ->> user: List of API servers
3839
39-
user ->> teaindex: Finding all product parts
40-
teaindex ->> user: List of product parts
41-
create participant tealeaf as TEA Leaf Index
42-
user ->> tealeaf: Finding all versions of a part
43-
tealeaf ->> user: List of all available versions (paginated)
44-
create participant teacoll as TEA Collection
45-
user ->> teacoll: Finding all artefacts for version in scope
46-
teacoll ->> user: List of artefacts and formats available for each artefact
47-
create participant artefact as Artefact
48-
user ->> artefact: Download artefact
40+
user ->> tea_product: Finding all product parts
41+
tea_product ->> user: List of product parts
42+
43+
user ->> tea_leaf: Finding all versions of a part
44+
tea_leaf ->> user: List of all available versions (paginated)
45+
46+
user ->> tea_collection: Finding all artefacts for version in scope
47+
tea_collection ->> user: List of artefacts and formats available for each artefact
48+
49+
user ->> tea_artifact: Download artefact
4950
5051
5152

‎api-flow/publisher.md‎

Lines changed: 41 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,96 +1,61 @@
11
# Overview of the TEA API from a producer standpoint
22

3-
* Note: Suggestion, input for the group
4-
3+
## Bootstrapping
54

65
```mermaid
7-
sequenceDiagram
8-
participant Vendor
9-
participant TEA_API
10-
participant TEA_Index
11-
participant Product_Repository
12-
participant SBOM_Generator
13-
participant VEX_Generator
14-
participant VDR_Generator
15-
participant Consumer
16-
17-
Vendor->>Product_Repository: Create new product version
18-
Product_Repository-->>Vendor: Product version created
19-
20-
Vendor->>TEA_API: POST /collection (Create new collection with FIRST_MENTION lifecycle event)
21-
TEA_API->>TEA_Index: Update index with new collection
22-
TEA_API-->>Vendor: Collection created (UUID)
23-
24-
Vendor->>TEA_API: POST /product (Create new TEA Product with TEI)
25-
TEA_API->>TEA_Index: Update index with new product
26-
TEA_API-->>Vendor: Product created (TEI)
27-
28-
Vendor->>TEA_API: POST /leaf (Create new leaf for product version)
29-
TEA_API->>TEA_Index: Update index with new leaf
30-
TEA_API-->>Vendor: Leaf created (UUID)
31-
32-
Vendor->>SBOM_Generator: Generate SBOM for new version (including TEI)
33-
SBOM_Generator-->>Vendor: CycloneDX SBOM (signed)
34-
SBOM_Generator-->>Vendor: SPDX SBOM (signed)
35-
36-
Vendor->>TEA_API: POST /artifact (Add CycloneDX SBOM)
37-
TEA_API->>TEA_Index: Update index with new artifact
38-
TEA_API-->>Vendor: CycloneDX artifact added
39-
40-
Vendor->>TEA_API: POST /artifact (Add SPDX SBOM)
41-
TEA_API->>TEA_Index: Update index with new artifact
42-
TEA_API-->>Vendor: SPDX artifact added
436
44-
Note over Vendor,VEX_Generator: CVE discovered in SBOM dependency graph
45-
46-
Vendor->>VEX_Generator: Generate VEX document (triage state)
47-
VEX_Generator-->>Vendor: CycloneDX VEX (signed, with bom-link)
48-
49-
Vendor->>TEA_API: POST /artifact (Add CycloneDX VEX as independent artifact)
50-
TEA_API->>TEA_Index: Update index with new artifact
51-
TEA_API-->>Vendor: CycloneDX VEX artifact added
52-
53-
Note over Vendor,TEA_API: Time passes, product enters beta testing
7+
sequenceDiagram
8+
autonumber
9+
actor Vendor
10+
participant tea_product as TEA Product
11+
participant tea_leaf as TEA Leaf
12+
participant tea_collection as TEA Collection
5413
55-
Vendor->>TEA_API: PUT /collection/{UUID} (Update collection with BETA_TESTING lifecycle event)
56-
TEA_API->>TEA_Index: Update index with lifecycle change
57-
TEA_API-->>Vendor: Collection updated
14+
Vendor ->> tea_product: POST to /v1/product to create new product
15+
tea_product -->> Vendor: Product is created and TEA Product Identifier (PI) returned
5816
59-
Note over Vendor,TEA_API: Product reaches General Availability
17+
Vendor ->> tea_leaf: POST to /v1/leaf with the TEA PI and leaf version as the payload
18+
tea_leaf ->> Vendor: Leaf is created and a TEA Leaf ID is returned
6019
61-
Vendor->>TEA_API: PUT /collection/{UUID} (Update collection with GENERAL_AVAILABILITY lifecycle event)
62-
TEA_API->>TEA_Index: Update index with lifecycle change
63-
TEA_API-->>Vendor: Collection updated
20+
Vendor ->> tea_collection: POST to /v1/collection with the TEA Leaf ID as the and the artifact as payload
21+
tea_collection ->> Vendor: Collection is created with the collection ID returned
6422
65-
Note over Vendor,VDR_Generator: Security researcher reports a new vulnerability
23+
```
6624

67-
Vendor->>VDR_Generator: Generate VDR for reported vulnerability
68-
VDR_Generator-->>Vendor: CycloneDX VDR (signed, with bom-link)
25+
## Release life cycle
6926

70-
Vendor->>TEA_API: POST /artifact (Add CycloneDX VDR as independent artifact)
71-
TEA_API->>TEA_Index: Update index with new artifact
72-
TEA_API-->>Vendor: CycloneDX VDR artifact added
27+
```mermaid
28+
sequenceDiagram
29+
autonumber
30+
actor Vendor
31+
participant tea_product as TEA Product
32+
participant tea_leaf as TEA Leaf
33+
participant tea_collection as TEA Collection
7334
74-
Note over Vendor,VEX_Generator: Vulnerability status changes (e.g., patch available)
35+
Note over Vendor,tea_leaf: Create new release
7536
76-
Vendor->>VEX_Generator: Generate new VEX document
77-
VEX_Generator-->>Vendor: New CycloneDX VEX (signed, with bom-link)
37+
Vendor ->> tea_leaf: POST to /v1/leaf with the TEA PI and leaf version as the payload
38+
tea_leaf ->> Vendor: Leaf is created and a TEA Leaf ID is returned
7839
79-
Vendor->>TEA_API: POST /artifact (Add new CycloneDX VEX as independent artifact)
80-
TEA_API->>TEA_Index: Update index with new artifact
81-
TEA_API-->>Vendor: New CycloneDX VEX artifact added
40+
Note over Vendor,TEA Leaf: Add an artifact (e.g. SBOM)
41+
Vendor ->> tea_collection: POST to /v1/collection with the TEA Leaf ID as the and the artifact as payload
42+
tea_collection ->> Vendor: Collection is created with the collection ID returned
8243
83-
Note over Consumer,TEA_API: Consumer performs a search
44+
```
8445

85-
Consumer->>TEA_API: GET /search (Search for products or collections)
86-
TEA_API->>TEA_Index: Query index
87-
TEA_Index-->>TEA_API: Search results
88-
TEA_API-->>Consumer: Return search results
46+
## Adding a new artifact
8947

90-
Note over Vendor,TEA_API: Product reaches End of Life
48+
```mermaid
49+
sequenceDiagram
50+
autonumber
51+
actor Vendor
52+
participant tea_product as TEA Product
53+
participant tea_leaf as TEA Leaf
54+
participant tea_collection as TEA Collection
9155
92-
Vendor->>TEA_API: PUT /collection/{UUID} (Update collection with END_OF_LIFE lifecycle event)
93-
TEA_API->>TEA_Index: Update index with lifecycle change
94-
TEA_API-->>Vendor: Collection updated
56+
Vendor ->> tea_leaf: GET to /v1/leaf with the TEA PI to get the latest version
57+
tea_leaf ->> Vendor: Leaf will be returned
9558
59+
Vendor ->> tea_collection: POST to /v1/collection with the TEA Leaf ID as the and the artifact as payload
60+
tea_collection ->> Vendor: Collection is created with the collection ID returned
9661
```

‎spec/README.md‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,23 @@ The OpenAPI 3.1 specification for the Transparency Exchange API is available in
88

99
We use the OpenAPI Generator with configuration per language/framework in the `generators` folder. An example is:
1010

11+
```bash
12+
docker run \
13+
--rm \
14+
-v "$(PWD):/local" \
15+
openapitools/openapi-generator-cli \
16+
batch --clean /local/spec/generators/typescript.yaml
1117
```
12-
docker run --rm -v "$(PWD):/local" openapitools/openapi-generator-cli batch --clean /local/spec/generators/typescript.yaml
13-
```
18+
19+
## Preview Specs
20+
21+
Fire up the `swagger-ui` with Docker from the root of the repository:
22+
23+
```bash
24+
docker run \
25+
-p 8080:8080 \
26+
-e SWAGGER_JSON=/koala/spec/openapi.json \
27+
-v $(pwd):/koala swaggerapi/swagger-ui
28+
```
29+
30+
And browse to [http://localhost:8080](http://localhost:8080).

0 commit comments

Comments
 (0)