CycloneDX
Proposal for more RESTful URL Semantics for SBOM Retrieval
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.
I'm fine with this approach, at least for artifact retrieval anyway. There will be additional APIs that provide data that will not be artifact based however.
@coderpatros thoughts?
This was actually my initial approach, and my personal preference. But I ended up going with a query string parameter as I wasn't sure how easy folks would find correctly encoding path segments. Especially with SPDX document identifiers. Where as, in my experience, developers regularly need to encode query string parameters, and languages/frameworks tend to provide helpers for that. Either way I'm happy to go with the general consensus on this one.
Since we are reworking the API and providing an OpenAPI spec we can certainly go for more restful. We are working on a new spec proposal - participate in the group or stay tuned :-)
