Supply Chain Integrity, Transparency, and Trust (SCITT) Reference APIs
draft-ietf-scitt-scrapi-10

## COMMENTS (non-blocking)

### Med's DISCUSS

I support Med Boucadair's DISCUSS point about the apparent conflict between `MUST` and `MAY`.

### Abstract

s/This document describes/This document *specifies*/ as this I-D aims for PS.

### Section 1

`The following resources MUST be implemented for conformance to this specification`, unsure whether the IETF is in the business of defining "conformance". Also, as all the refered sections are normative, this paragraph is fully redundant.

### Section 2

In the HTML rendering, it is unclear whether `* title:` is part of the numbered list just above. It also needs some leading text.

## Comments

### Section 2.2, paragraph 12
```
     If the kid values used by the service ({kid_value} in the request
     above) are not URL-safe, the resource MUST accept the base64url
     encoding of the kid value, without padding, in the URL instead.
```
Does this imply that clients determine the request format based on whether the
kid_value they're querying is URL-safe? Can a client infer whether *all* kid
values are URL-safe based on examining one kid?

I'd be inclined to make this say either that resources must exist for both the
raw kid value (if URL-safe) and the base64url-encoded value, or that a server
publishes somewhere whether it commits to URL-safe kid values.

### Section 2.3.2, paragraph 1

I would have expected 202 here, but 303 also seems defensible. No
change necessarily required, just review the definitions of each to be sure.

### Section 2.4.1, paragraph 3
```
     The location MAY be temporary, and the service may not serve a
     relevant response at this Location after a reasonable delay.
```
There are several instances of this sentence; I'd suggest a slight rephrase
throughout to
ensure "may not serve" is read as permission not to serve rather than a
prohibition on serving. "...the server might remove the resource after a
reasonable delay."

### Missing references

No reference entries found for these items, which were mentioned in the text:
`[RFC9162]` and `[RFC7231]`.

(But note that 7231 is obsoleted by 9110, so you probably want to update that
text rather than adding the reference.)

## Nits

All comments below are about very minor potential issues that you may choose to
address in some way - or ignore - as you see fit. Some were flagged by
automated tools (via https://github.com/larseggert/ietf-reviewtool), so there
will likely be some false positives. There is no need to let me know what you
did with these suggestions.

### Typos

#### Section 2.1, paragraph 9
```
-    The Transparency Service MAY stop returning at that resource the keys
-                                                ---------------------
```

### Section 6.1.1, paragraph 2
```
     URI suffix: scitt-keys Change controller: IETF Specification
     document(s): RFCthis Status: Permanent Related information:
     [I-D.draft-ietf-scitt-architecture]
```
I suspect this is not the formatting you intended for this list.

### Grammar/style

#### Section 2.3.1, paragraph 5
```
 "Signed Statement contained a non supported algorithm" } HTTP/1.1 400 Bad Re
                               ^^^^^^^^^^^^^
```
This expression is usually spelled with a hyphen.

#### Section 2.4.1, paragraph 7
```
 "Signed Statement contained a non supported algorithm" } HTTP/1.1 400 Bad Re
                               ^^^^^^^^^^^^^
```
This expression is usually spelled with a hyphen.

#### Section 2.4.5, paragraph 1
```
f authorization or preventing denial of service attacks. If Authentication i
                              ^^^^^^^^^^^^^^^^^
```
It appears that hyphens are missing.

#### Section 2.5.1, paragraph 3
```
al of Service Attacks While denial of service attacks are very hard to defen
                            ^^^^^^^^^^^^^^^^^
```
It appears that hyphens are missing.

#### Section 2.5.2, paragraph 4
```
 limited risk to eavesdropping. Nonetheless transparency may mean 'within a
                                ^^^^^^^^^^^
```
A comma may be missing after the conjunctive/linking adverb "Nonetheless".