Re: [httpapi] I-D: api-catalog: A well-known URI to help discovery of APIs

Hi all,

I have looked at the discussion thread and the latest version of the
api-catalog spec and arrived at a possible other approach for the linkset:
* It has an anchor for each API endpoint
* It uses the existing link relation types service-desc, service-doc, and
service-meta as defined in Erik's
https://www.rfc-editor.org/rfc/rfc8631.html

Advantages I see:
- Re-use of existing well-documented link relation types
- Ability to point at both machine readable and human readable documentation
- Ability to advertise support for standards/specifications for which no
machine readable API documentation exists.

This is a rendition of Kevin's example from the I-D according to that
approach:

{
  "linkset": [
    {
      "anchor": "https://developer.example.com/apis/foo_api",
      "service-desc": [
        {
          "href": "https://developer.example.com/apis/foo_api/spec",
          "type": "text/n3"
        }
      ],
      "service-doc": [
        {
          "href": "https://developer.example.com/apis/foo_api/doc",
          "type": "text/html"
        }
      ]
    },
    {
      "anchor": "https://developer.example.com/apis/bar_api",
      "service-desc": [
        {
          "href": "https://developer.example.com/apis/bar_api/spec",
          "type": "application/json"
        }
      ],
      "service-doc": [
        {
          "href": "https://developer.example.com/apis/bar_api/doc",
          "type": "text/plain"
        }
      ]
    },
    {
      "anchor": "https://developer.example.com/apis/cantona_api",
      "service-desc": [
        {
          "href": "https://developer.example.com/apis/cantona_api/spec",
          "type": "text/n3"
        }
      ],
      "service-doc": [
        {
          "href": "https://developer.example.com/apis/cantona_api/doc",
          "type": "text/html"
        }
      ]
    }
  ]
}

Greetings

Herbert

On Mon, Jun 5, 2023 at 5:09 PM Kevin Smith, Vodafone <Kevin.Smith=
40vodafone.com@dmarc.ietf.org> wrote:

> Hi,
>
> https://datatracker.ietf.org/doc/draft-smith-api-catalog/
>
> V0.2 published with a suggested linkset format and two link relations. Per
> earlier discussion, these changes are intended to facilitate
> machine-readability/automated API discovery and usage, with the draft
> specifying that the api-catalog media type be a linkset containing API
> bookmarks. I think that following a bookmark should return a description
> with sufficient information for automated API usage,  and I've made a note
> that RESTdesc may provide the appropriate semantic binding. But any advice
> welcome!
>
> All best
> Kevin
>
>
> 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