Apologies, this a long piece of feedback on draft-ietf-scitt-architecture, I hope it is useful. From the perspective of someone who is not an expert in the security field, the document does a good job of explaining the problem being solved, the use cases where it is valuable and the mechanics of the process of signing statements and producing transparent statements. The roles of each of the participants are clearly explained. The majority of my feedback is around the specification of the Transparency Service API in section 8 (https://www.ietf.org/archive/id/draft-ietf-scitt-architecture-01.html#name-transparency-service-api-th). From my perspective, the goal of this section should be to ensure interoperability while imposing the minimum set of constraints on the implementation of the Transparency service. Resource Paths -------------- The current draft defines a fixed set of resource paths relative to a base URL. However, BCP 56 https://www.rfc-editor.org/rfc/rfc9205.html#section-4.4.1 recommends providing paths via a discovery document that contains URI Templates for the required resources exposed by the API. While the approach proposed by BCP56 is the most flexible approach, it does make it more challenging to document and describe the API surface in a way that is familiar to most developers. It is worth considering whether the shape of this API surface is expected to grow over time. If significant change is expected then the additional complexity of the discovery document may be warranted. Base URL -------- The document should make some statement about how a client might acquire a base URL. Is it worth defining a .well-known URL for Transparency Services? Would a DNS SRV record be appropriate? Should a link relation be defined so that other content could point to the Transparency Service via an embedded link? Standard HTTP behavior ---------------------- The document should avoid restating standard HTTP behavior as described by RFC9110. Describing the semantics of 4xx, 5xx, 503 and the retry-after header is neither necessary nor appropriate. Error Content ------------- Use and referencing of RFC7807 is good. However, I don't believe the document should reiterate how to specify the response Content-Type header. That content can be in an implementer's guide. It is not clear to me where a developer might see the "Error code: malformed". It looks like some of the error responses have not been updated to be using RFC7807 syntax. Response payloads ----------------- A number of the API responses return a Content-Type: application/json but have some form of expected response shape. This kind of tight coupling between resource paths and expected response shapes is not ideal for internet standards as it is not resilient to change and does not enable clients to negotiate for content, or for intermediaries to have visibility into the content. One suggestion would be to use the document to register a media type such as application/scitt-message+json and then define the media type to have structure such as this structure described in CDDL: scitt-message= { ? registration : registration ? operation : operation } registration = { entryUrl: string } operation = { operationUrl: string status: running / succeeded / failed ? error: error } error = { type: string detail: string } This allows the media type in the response content-type to communicate the semantics of the response message. The structure is flexible enough to return both the registration information and/or the state of the running operation. This structure could easily be extended to add support for other message kinds needed by the transparency service. By providing a entryUrl property in the registration, the client does not need to have knowledge of how to construct valid URLs to access the registration entry. Additionally it avoids the need to return the Location header in the 200 response from the Operation resource. Location headers in 200 responses are not defined. Additionally the semantics of Location header are not defined for 202 responses in RFC 9110. As the 202 response does return the representation of the operation resource, it would be appropriate to return a Content-Location header that contains the Operation URL to provide the client a place to continue to poll for status. Here is a suggestion of how these calls might look using the suggestions made: ## Create an entry POST /entries Content-Type: application/cose [SCITT COSE_Sign1 message] 201 Created Content-Type: application/scitt-message+json Location: /entries/ { "registration": { "entryUrl": "/entries/" } } ### Create an entry with a 202 response POST /entries Content-Type: application/cose [SCITT COSE_Sign1 message] 202 Accepted Content-Type: application/scitt-message+json Content-Location: /operations/ { "operation": { "operationUrl": "/operations/", "status": "running" } } ### Poll an operation that has not finished GET /operation/ Content-Type: application/cose [SCITT COSE_Sign1 message] 200 Ok Content-Type: application/scitt-message+json { "operation": { "operationUrl": "/operations/", "status": "running" } } ### Poll an operation that has finished GET /operation/ Content-Type: application/cose [SCITT COSE_Sign1 message] 200 Ok Content-Type: application/scitt-message+json { "operation": { "operationUrl": "/operations/", "status": "succeeded" }, "registration": { "entryUrl": "/entries/" } } Overall, this specification looks like it has been well thought out and is solving a valuable problem. Hopefully, my suggestions around the Transparent API Services will provide some value.