Httpdir early review of draft-ietf-scitt-scrapi-01

[Darrel Miller via Datatracker <[e-mail]>]

Reviewer: Darrel Miller
Review result: On the Right Track

The following is an early review of draft-ietf-scitt-scrapi-01 on behalf of the
HTTP Directorate.

Kudos for the recent revision to the draft. Much of my previous feedback has
been addressed in this new draft.

## 2 - Endpoints

While I understand that some other specifications (e.g. RFC 6748) use the term
endpoints, RFC 9110 uses the term "resource". There is some precedent for using
the term "API Endpoint" but the term endpoint is muddied by alternate uses of
the term to represent a device.

> The following HTTP endpoints are mandatory to implement

It seems problematic to define a mandatory requirement using a term that is not
defined by HTTP.

### 2.1.1

The use of a link relation type for pointing to the transparency configuration
would be a more flexible solution over using .well-known.  Using .well-known
requires out of band communication of the hostname and limits there to being
only one configuration document per hostname. Providing a link relation type
would provide the flexibility for Transparency Service providers to host the
described resources at any base URL.

> Additional fields may be present. Fields that are not understood MUST be
ignored.

RFC8259 uses the term `member` instead of `field.

Where is the response payload for transparency configuration defined?

### 2.1.2

What does it mean to say "Authentication MUST be implemented"?  Does that
require the use of the HTTP authorization header field? Or could I use an api
key in the header or query parameter? Is mututalTLS OK?

> If registration succeeds the following identifier MAY
> be used to refer to the Signed Statement that was
> accepted:
>
> urn:ietf:params:scitt:signed-statement:sha-256
> :base64url:5i6UeRzg1...qnGmr1o

This exact identifier for any signed statement? Or is this an example of an
identifier that can be found somewhere else?  Is there an expectation that the
client parses the returned Location header to construct the above value?

Is this `/entries` URL fixed?  As discussed in BCP56
(https://www.rfc-editor.org/rfc/rfc9205.html#name-specifying-urls) it is not
appropriate to define fixed paths at the root of a host. There needs to be some
discovery mechanism to identify the API resources.

### 2.2.1  Issue Statement

In the example request the Accept field says `application/json`but the response
is `application/cose`.  Is this intentional to show the example server doesn't
support `application/json` responses?  Do they ever?

### 2.2.4 Resolve Receipt

Is the first response example supposed to have a content-type field value of
`application/scitt.receipt+cose``

### 2.2.5 Resolve Issue

What is the schema/media type of the returned response? The response
content-type does not allow a caller to understand the semantics of the
response.

### 2.2.7 Resolve Issuer DID

What does it mean to include a "deprecated" resource in this document? Why not
just not include it?

## 5.4 Media Type Registration

The media type to be registered should be `application/scitt-receipt+cose`. 
The period has a reserved meaning as per RFC6838.

> Note that this means that facet-less
> standards-tree registrations cannot use
> periods in the subtype name.
https://www.rfc-editor.org/rfc/rfc6838#section-4.2

In general I think this draft is on the right track and with some minor
adjustments and clarifications can satisfy the best practices for HTTP
application protocols as outlined in BCP 56.

Regards,

Darrel