[httpapi] Re: Genart last call review of draft-ietf-httpapi-api-catalog-05

["Kevin Smith, Vodafone" <[e-mail]>]

HI Mallory,

Many thanks for your helpful review. I've attempted to address the comments in the new version -06 as follows:

> * www.example.com vs example.com vs example.net-- these examples appear
> arbitrarily different, eg it is not clear when the subdomain or the tld bears
>  upon the advice and when it is just a conventional oversight. Please be
> thoroughly consistent throughout and if there is a change, explicitly state
>  why that change is important to implementation.

Fix in -06:
Explained the use of the various *.example.* FQDNs in the Notational Conventions section.

> Relatedly, in sections 2-4 the advice could be clearer.
> *section 4 should build upon section 2, specifically remove the first
> bullet point from section 4 because it is redundant to section 2 and would
> give readers the wrong idea that the advice in section 2 needs to change
> materially on this point (it seems to me that it doesn't).

Fix in -06:
removed redundant bullet from section 4

> section 4 neglects to say what should happen if the Publisher is not
> the domain authority for example.net:

> If the Publisher is also the domain authority for example.net, which
> also hosts a selection of their APIs, then a request to
> www.example.net/.well-known/api-catalog SHOULD return a redirect as
> follows.

Fix in -06:
made a point about this in Notational Conventions, and added text and an example in section 4 to explain the scenario where the Publisher is not the authority for a given secondary domain.

> Lastly perhaps consider the use of HTTP(S), a new convention-- I haven't
> seen this usage anywhere else in documentation. You could use HTTP/HTTPS, or
> you might controversially perhaps use just HTTPS and describe in the security
> considerations why you are not being explicit about the use of HTTP (given we
> have moved on from this standard 20 years ago).

Fix in -6:
Removed all mentions of HTTP, HTTP(S), and http:// . HTTPS and https://  are now used throughout, and TLS is explicitly recommended in the Security Guidelines.

All best,
Kevin

C2 General