[httpapi] Re: AD Review of draft-ietf-httpapi-api-catalog-03

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

Hi Darrel, all,

> The latest update to the api-catalog draft effectively tries to "pick a winner" in the api-catalog format space by making the use of linkset a MUST.  That is likely going to hurt adoption.
> [...]
> I think it would be reasonable to reference the Linkset media type in the well-known registration as a recommendation.  Maybe even a SHOULD.

I agree... the draft lists several API catalog formats in use, and I'm not aware of any evidence showing one as being significantly more popular - so Linkset got the recommendation because it's the only one that's an RFC. But "MUST" will likely deter takeup from API publishers using apisjson,  HAL etc. ,  so I'm hoping that the requirement 'defines a format and associated media type(s)' can be interpreted as supporting "SHOULD" for the recommended format, as well as listing alternatives that can be negotiated.

Ref. RFC 8615 sec.3
"At a minimum, a registration will reference a specification that
defines the format and associated media type(s) to be obtained by
dereferencing the well-known URI, along with the URI scheme(s) that
the well-known URI can be used with."

All best,
Kevin

PS direct link to the diff related to this in [1]

[1] https://github.com/ietf-wg-httpapi/api-catalog/commit/b738f3de9dbfa8f6451a03601a093ce0de6858b2#diff-fc4c173d5f72637f6e6434c2cfa69cefba99ad9a95d11862bb067c33fcf5a782L197

C2 General