Advertising HTML-encoded AsyncAPI definition documents in PubSub enabled OGC API landing pages

[ghobona]

This issue is related to opengeospatial/ogcapi-common#329 , however is more severe for HTML-encoded definition documents.

Consider the following fragment from the links in a landing page.

        {
            "rel": "service-doc",
            "type": "text/html",
            "title": "The OpenAPI definition as HTML",
            "href": "http://localhost:5000/openapi?f=html",
            "hreflang": "en-US"
        }

If a server wishes to advertise links to HTML-encoded AsyncAPI definition documents and HTML-encoded OpenAPI definition documents, there is a need to either provide a rel or type that allows such distinction to be made. Any thoughts on how this could be achieved?

Note that the reason why the issue is more severe for HTML-encoded definition documents, is because at least for JSON-encoded definition documents there is a specific media type for OpenAPI definition documents.

[ghobona]

Cc: @tomkralidis @jerstlouis @cportele

[jerstlouis]

It would not be possible to link to both an HTML rendering of an OpenAPI definition as well as an HTML rendering of the AsyncAPI if we rely on using the same service-doc link relation type.

For the service-desc, there is also a potential for conflict if not using a media-type specific to Async API (but using application/json) with any other API definition language that also does not have its own media type (not an issue with OpenAPI, which does have its own media type).

Is it too late to use something else than service-desc / service-doc?

Would it make sense to use something specific for describe async APIs ?

cc. @tomkralidis

[tomkralidis]

For the service-desc case, note that for service description the following open issue exists, however it looks like the issue has gone stale (aka a good time to bring back to life there!).

[ghobona]

This issue has been moved from the OGC API - Common repo to the OGC API - EDR repo because that is where the PubSub extension is being developed.

[ghobona]

This issue was discussed in the Joint OGC API SWGs session on 2024-03-27 session and a proposal to declare an OGC-specific relation type was approved.

[cportele]

Apologies for not attending the Joint OGC API SWG session, but I do not see the argument for a different link relation type. service-doc applies both to a HTML documentation derived from an OpenAPI definition or an AsyncAPI definition. If there are two service-doc links, the human reader will understand their scope and that they describe two different APIs. And the title link attribute should clearly specify the meaning of the link target.

At least, if OGC defines a special AsyncAPI link relation type, it should not be mandatory to use it for links to the documentation of an event-driven API.

In any case, the type link attribute is only a hint.

[chris-little]

EDR API 115 agreed not to change anything in the Part 2 spec but suggest a link with a media type suitable for all OGC APIs until the AsyncAPI community have an IANA registered link. @ghobona should be consulted. We suggest modelling on OpenAPI media type:

• application/vnd.oai.openapi (YAML variant) -> application/vnd.aai.asyncapi
• application/vnd.oai.openapi+json (JSON only variant) -> application/vnd.aai.asyncapi+json
• application/vnd.oai.openapi;version=2.0 -> application/vnd.aai.asyncapi;version=2.0

@tomkralidis will propose this to the AsyncAPI community.

The IANA OpenAPI proposal probably will look like:

• application/openapi+yaml;version=3.1
• application/openapi+yaml;version=3.0;q=0.5
• application/openapi+json;q=0.3

[tomkralidis]

ACTION: add note to 8.2.1 that AsyncAPI media type may change in the future.

[cportele]

@tomkralidis

Since RFC 9512 has recently been published, it should be application/vnd.oai.asyncapi+yaml for the YAML variant, that is, with the suffix.

Also, I do not understand the use of oai. What does this refer to? Should this be aai for the "AsyncAPI Initiative"?

[tomkralidis]

• @cportele I've updated @chris-little 's text above (indeed aai is to be used for a vendor definition), soapplication/vnd.aai.asyncapi+yaml
• note added to specification (Part 2 RFC comments update #539) that AsyncAPI media type may change in the future
• sent a note to the AsyncAPI community in define formal media type (MIME type) for AsyncAPI Object asyncapi/spec#936 (comment)

[m-mohr]

#539 still uses application/json, right? Is this planned to be updated?

[tomkralidis]

No, not until there is clarification from the AsyncAPI community. There is enough delineation for now of rel=service-desc between the OpenAPI media type and type=application/json (there is a possibility that rel=service-desc and type=application/json may get overloaded if one has multiple JSON-based service-desc endpoints, but IMHO that is an edge case atm).