Provide OpenAPI Sped for REST Endpoints

Hello 👋. I have quickly reviewed the spec draft here and noticed that only CycloneDX and SPDX are identified. Is SWID, more specifically the compact CBOR alterntive in IETF RFC9393 supported? If not, would you open to contributions to align identifiers and other metadata from this other BOM format in this API spec?

The current URL semantics for retrieving a BOM uses query parameters:

bom-retrieval-url    = system-url "?" bom-identifier-query
bom-identifier-query = "bomIdentifier=" bom-identifier
bom-identifier       = *( pchar / "/" / "?" )
                        ; an identifier that uniquely identifies a BOM
                        ; pchar as defined in RFC3986

However, in accordance with RESTful principles, using the path to represent resources is preferred over query parameters, especially when a resource can be uniquely identified by a specific parameter.

To better adhere to RESTful design principles, I'd like to propose updating the URL semantics as follows:

bom-retrieval-url    = system-url "/" bom-identifier
bom-identifier       = *( pchar / "/" / "?" )
                        ; an identifier that uniquely identifies a BOM
                        ; pchar as defined in RFC3986

Where the bom-identifier directly follows the system-url, making the URL structure clearer and more intuitive.

The current design for SBOM submission already adheres to RESTful principles. Specifically, SBOMs are submitted using a POST request to:

bom-submission-url = system-url

By modifying the retrieval URL, we can achieve consistent RESTful design across both submission and retrieval operations.

Use of Query Parameters for Filtering:
While proposing to change the URL semantics for retrieval, it's worth noting that query parameters are still valuable and can be used on the system-url for filtering mechanisms. For instance, when searching or narrowing down results based on certain criteria, query parameters can efficiently convey this information. The distinction is that for direct and unique resource identification, as with the bomIdentifier, the path component is preferable in line with RESTful design.

The idea behind a BOM Meta endpoint is to provide format, hash, and external signature information.

The BOM Meta retrieval would work similar to the existing BOM retrieval, but would return metadata rather than the BOM itself.

bom-meta-url = system-url "/" bom-identifier
bom-identifier    = segment
                        ; an identifier that uniquely identifies a BOM
                        ; NOTE: MUST be appropriately URI encoded
                        ; segment as defined in RFC3986

As an example, here's a snippet response for what I'm thinking about being returned:

{
  "spec": {
    "format": "CycloneDX",
    "version": "1.4",
    "mime-type": "application/vnd.cyclonedx+json",
  },
  "published": "2022-03-07T15:50+00Z",
  "checksum": [
    { "alg": "SHA-256", "value": "CF80CD8..." },
    { "alg": "SHA-512", "value": "CF80CD8..." },
    { "alg": "SHA3-256", "value": "CF80CD8..." },
    { "alg": "SHA3-512", "value": "CF80CD8..." },
    { "alg": "BLAKE3", "value": "CF80CD8..." }
  ],
  "signature": [
  
  ]
}

I think alg should be an enum with only those supported algorithms.

As for signatures, it would be ideal if we could support external signature files, signature services (e.g sigstore), and external inline.

This allows polling for latest version of a BOM without having to retrieve it entirely.

We need to reference MUD in the spec and provide a statement that says the BOM Exchange API is compatible with MUD, possibly providing an example of interop.

There's an outstanding issue upstream in swagger-ui swagger-api/swagger-ui#5433

A Bom Post API should accept a Bom payload as Base64 (URL Safe) encoded format.

Dependency track application also accepts Bom JSON as Base64 Encoded data.

Project CycloneDX/cyclonedx-bom-repo-server implemented Post API to accept it as plain text.

Curl sample from CycloneDX/cyclonedx-bom-repo-server

curl -X POST "https://www.example.com/bom" -H "accept: /" -H "Content-Type: application/vnd.cyclonedx+json; version=1.3" -d "{"bomFormat":"CycloneDX","specVersion":"1.3","serialNumber":"urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79","version":1,"components":[{"type":"library","name":"acme-library","version":"1.0.0"}]}"```

As a user, i do not know the URN of the SBOM I want to retrieve. This specification should define how I can determine the URN for an SBOM I want to retrieve, ideally by way of CPE, PURL or SWID, or potentially even by software file hash or some other unique identifier.

Add Support of REST API Versioning.

Are you considering an endpoint that could be given a PURL and return a list of bom-identifiers for SBOMs that describe that PURL? It might also be useful to have an endpoint to find bom-identifiers that depend on a PURL, but the former would be the more immediate need.