Re: [httpapi] api-catalog new version and Git repository

On Tue, Feb 27, 2024 at 6:35 PM Kevin Smith, Vodafone <
Kevin.Smith@vodafone.com> wrote:

> Hi Herbert,
>
>
>
> Thanks for this (and also your previous suggestion, which I will
> incorporate).
>
>
>

Thanks for your response. I insert some comments, below.

> > whether the I-D should have some wording regarding the possible/allowed
> use of api-catalog links at other URIs?
>
>
>
> Yes, the I-D is not intended to restrict anyone who wants to do that.
> Section 3 is written in that spirit, although that is from the perspective
> of a Publisher with APIs across several domains, each of which can publish
> the /.well-known/api-catalog URI. It recommends that one of the locations
> host the canonical version of the API Catalog, and I think the same would
> apply if the catalog were hosted at other URIs. You could still make use of
> /.well-known/api-catalog ato redirect to another URI if desired.
>
>
>

Understood. But in these cases, the use of the api-catalog link seems to
remain tied to the /.well-known/api-catalog URIs. I was asking about using
api-catalog links at locations other than /.well-known/api-catalog URIs.

> > I think it would be rather helpful if that link could (also) be provided
> at the predictable URI
>
>
>
> To my thinking {example.com}/.well-known/api-catalog is a predictable
> URI, but I suspect I may be misunderstanding your comment…
>
>
>

Oh. I had interpreted example.com to be the predictable URI. And, since
/.well-known/api-catalog is predictable as a result of this specification,
that also makes example.com//.well-known/api-catalog predictable. Anyhow,
my suggestion was that it might be helpful if the api-catalog link could
(also) be provided at URIs such as example.com. I'm not suggesting
requiring it. Merely allowing it.

> > I was wondering whether it would make sense to treat discovery via
> api-catalog links a bit more as an equally viable approach
>
>
>
> Yes, that makes sense to me - Section 6 states:
>
>
>
> "api-catalog": the 'api-catalog' link relation identifies a target
> resource that represents a list of APIs of which the context resource is a
> member.”
>
>
>
> …but that only accounts for use of that link relation from one of the
> catalog members. So I will clarify that the link relation can be used from
> other context resources, i.e. “the 'api-catalog' link relation identifies
> a target resource that represents a list of APIs available from the
> Publisher of the context resource.” Does that cover your suggestion?
>
>
>

Yes, that would be great! Thanks!

Greetings

Herbert

> Thanks again!
>
> Kevin
>
>
>
>
>
> C2 General
>
> *From:* Herbert Van de Sompel <hvdsomp@gmail.com>
> *Sent:* 27 February 2024 08:38
> *To:* Kevin Smith, Vodafone <Kevin.Smith@vodafone.com>
> *Cc:* httpapi@ietf.org; Herbert Van de Sompel <hvdsomp@gmail.com>
> *Subject:* Re: [httpapi] api-catalog new version and Git repository
>
>
>
> You don't often get email from hvdsomp@gmail.com. Learn why this is
> important <https://aka.ms/LearnAboutSenderIdentification>
>
> *External Email:* Be cautious about the sender email address, attachments
> and links. If uncertain use Report Message button.
>
> hi Kevin, all,
>
>
>
> I have some further questions/suggestions regarding the current version of
> the API Catalog I-D:
>
>
>
> * I thought it would be helpful if the api-catalog link could also be
> provided at URIs other than /.well-known/api-catalog. For example, I think
> it would be rather helpful if that link could (also) be provided at the
> predictable URI. I assume that this would be OK but I was wondering whether
> the I-D should have some wording regarding the possible/allowed use of
> api-catalog links at other URIs?
>
>
>
> * More generally speaking, the I-D focuses on the well-known URI approach,
> cf. e.g. the title "a well-known URI to help discovery of APIs". Don't get
> me wrong, I have nothing against the well-known approach. But I was
> wondering whether it would make sense to treat discovery via api-catalog
> links a bit more as an equally viable approach rather than as an approach
> to support discovery when issuing an HTTP HEAD against the well-known URI?
>
>
>
> Greetings
>
>
>
> Herbert
>
>
>
>
>
> On Fri, Feb 9, 2024 at 2:28 PM Kevin Smith, Vodafone <Kevin.Smith=
> 40vodafone.com@dmarc.ietf.org> wrote:
>
> Hi all,
>
>
>
> I have uploaded a new version of  "api-catalog: A well-known URI to help
> discovery of APIs", draft-ietf-httpapi-api-catalog-01  [1].
>
>
>
> Changes from draft 00, following feedback at IETF 118 and on-list:
>
> * added 'Publisher' to terminology
>
> * added section for APIs distributed across multiple domains
>
> * added section for private/internal APIs
>
> * expanded list of formats for the API Catalog document
>
> * made Linkset the recommended format
>
> * referenced  'item' link relation as a member of an API Catalog
>
> * typos/rewording
>
>
>
> You can now raise issues/pull requests at the Git repository [2]
>
>
>
> All best,
>
> Kevin
>
>
>
> [1]
> https://www.ietf.org/archive/id/draft-ietf-httpapi-api-catalog-01.html
>
> [2] https://github.com/ietf-wg-httpapi/api-catalog
>
>
>
>
>
>
>
>
>
> C2 General
>
> --
> httpapi mailing list
> httpapi@ietf.org
> https://www.ietf.org/mailman/listinfo/httpapi
>
>
>
> --
>
> ==================
>
> Herbert Van de Sompel
>
> https://hvdsomp.info
>
> https://orcid.org/0000-0002-0715-6126
>

-- 
==================
Herbert Van de Sompel
https://hvdsomp.info
https://orcid.org/0000-0002-0715-6126