Merge pull request #153 from oej/create-beta

Add BETA information to README

Author: oej

README.md

@@ -8,12 +8,27 @@
 
 # CycloneDX Transparency Exchange API Standard
 
-The Transparency Exchange API is being worked on within the CycloneDX community
+The Transparency Exchange API (TEA) is being worked on within the CycloneDX community
 with the goal to standardise the API in ECMA. A working group within ECMA TC54 has been
 formed - TC54 TG1. The working group has a slack channel in the CycloneDX slack space.
 
 ![](images/tealogo.png)
 
+## Status of the standard: Beta 1
+
+TEA is now in beta 1. This beta focuses on the consumer side of the API. Work on the
+publisher API will start after the beta. The idea is to get implementation feedback
+early on the current specification in order to move forward towards a first official
+version of the standard. Feedback will be gathered in the Hackathon at OWASP AppSec
+Global in Barcelona May 28 as well as in the meetings and slack channel.
+
+We encourage developers to start with both client and server implementations of TEA and
+participate in interoperability tests. These will be organised both as hackathons and
+informally using the Slack channel.
+
+There will likely be multiple beta releases. We will announce these by adding new
+tags in the repository as well as in the slack channel.
+
 ## Introduction
 
 This specification defines a standard, format agnostic, API for the exchange of
@@ -78,6 +93,10 @@ Insights allows for “limited transparency” that can be asked and answered us
 - Our biweekly meetings are available on [YouTube playlist: Project Koala](https://www.youtube.com/playlist?list=PLqjEqUxHjy1XtSzGYL7Dj_WJbiLu_ty58)
 - KoalaCon 2024 - an introduction to the project - can be [viewed on YouTube](https://youtu.be/NStzYW4WnEE?si=ihLirpGVjHc7K4bL)
 
+## Contributors
+
+Contributors are listed in the [Contributors](contributors.md) file.
+
 ## Terminology
 
 - API: Application programming interface

api-flow/consumer.md

@@ -11,12 +11,12 @@ by other means. It contains one or multiple components.
 
 - __List of TEA Components__: Components are components of something that is part of a product.
   Each Component has it's own versioning and it's own set of artifacts.
-- __List of TEA releases__: Each component has a list of releases where each release has a timestamp and
+- __List of TEA Releases__: Each component has a list of releases where each release has a timestamp and
   a lifecycle enumeration. They are normally sorted by timestamps. The TEA API has no requirements of
 type of version string (semantic or any other scheme) - it's just an identifier set by the manufacturer.
-- __List of TEA collections__: For each release, there is a list of TEA collections as indicated
+- __List of TEA Collections__: For each release, there is a list of TEA collections as indicated
   by release date and a version integer starting with collection version 1. 
-- __List of TEA artifacts__: The collection is unique for a version and contains a list of artifacts.
+- __List of TEA Artifacts__: The collection is unique for a version and contains a list of artifacts.
   This can be SBOM files, VEX, SCITT, IN-TOTO or other documents.  Note that a single artifact
   can belong to multiple versionsof a Component and multiple Components.
 - __List of artifact formats__: An artifact can be published in multiple formats.
@@ -105,6 +105,63 @@ sequenceDiagram
     user ->> tea_artifact: Request to download artifact
     tea_artifact ->> user: Artifact
 
+```
+
+## API flow based on cached data - checking for a new release
+
+In this case a TEA client knows the component UUID and wants to check the status of the
+used release and if there's a new release. The client may limit the query with a given date
+for a release.
+
+```mermaid
+
+---
+title: TEA client flow with direct query for release
+---
+
+sequenceDiagram
+    autonumber
+    actor user
 
+    participant tea_product as TEA Product
+    participant tea_component as TEA Component
+    participant tea_release as TEA Release
+    participant tea_collection as TEA Collection
+    participant tea_artifact as TEA Artefact
+
+    user ->> tea_release: Finding a specific version/release
+    tea_release ->> user: List of releases and collection id for each release
 
 ```
+
+## API flow based on cached data  - checking if a collection changed
+
+In this case a TEA client knows the release UUID, the collection UUID, and the
+collection version from previous queries. If the given version is not the same,
+another query is done to get reason for update and new collection list of artifacts.
+
+
+```mermaid
+
+---
+title: TEA client collection query
+---
+
+sequenceDiagram
+    autonumber
+    actor user
+
+    participant tea_product as TEA Product
+    participant tea_component as TEA Component
+    participant tea_release as TEA Release
+    participant tea_collection as TEA Collection
+    participant tea_artifact as TEA Artefact
+
+
+    user ->> tea_collection: Finding the current collection, including version
+    tea_collection ->> user: List of artefacts and formats available for each artefact
+
+    user ->> tea_collection: Request to access previous version of the collection to compare
+    tea_collection ->> user: Previous version of collection
+
+```

api-flow/publisher.md

@@ -1,5 +1,7 @@
 # Overview of the TEA API from a producer standpoint
 
+This is input for the working group.
+
 ## Bootstrapping
 
 ```mermaid