Subject: [core] API specification via OpenAPI & AsyncAPI

From: Jonathan Beri <[email-masked]>
Date: Thu, 23 Apr 2020 12:14:32 -0700

OpenAPI (openapis.org) is a popular API specification format under the
Linux Foundation. Use cases for an API definition documents include
interactive documentation, code generation for documentation, clients, and
servers and automation of test cases. Recently I learned about AsyncAPI (
asyncapi.com), which is a sibling spec for asynchronous, event-driven APIs.

I believe it would provide an improved developer experience for the reasons
listed above to have an API specification format for CoAP and groupcomm. It
should be feasible to adopt OpenAPI for the request-response features of
CoAP and AsyncAPI for the group comms. There's some interest
<https://github.com/asyncapi/asyncapi/pull/104> in the AsyncAPI community
to see CoAP support, which I'd be interested in facilitating.

Thoughts? There may be some overlap between the Link Format and Resource
Directory specs, but I believe those can be mitigated - or even supported
via code generation. Are there any other related efforts that should be
considered? If not, there's a lot of value around the community and
ecosystem of OpenAPI and now AsyncAPI.

-- 
Jonathan Beri
linkedin.com/in/jonathanberi <https://www.linkedin.com/in/jonathanberi/>

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 24 Apr 2020 01:08:35 +0200

Hi Jonathan,

questions like this are being actively discussed in the T2TRG under the name of "WISHI" (Work on IoT Semantic/Hypermedia Interoperability, http://wishi.space).
We'll have the next WISHI web conference today (er, tomorrow US time):
<https://mailarchive.ietf.org/arch/msg/t2trg/FC63LiID6CoXYYwdCRpOfIhTO58>

Grüße, Carsten

> On 2020-04-23, at 21:14, Jonathan Beri <[email-masked]> wrote:
> 
> OpenAPI (openapis.org) is a popular API specification format under the Linux Foundation. Use cases for an API definition documents include interactive documentation, code generation for documentation, clients, and servers and automation of test cases. Recently I learned about AsyncAPI (asyncapi.com), which is a sibling spec for asynchronous, event-driven APIs.
> 
> I believe it would provide an improved developer experience for the reasons listed above to have an API specification format for CoAP and groupcomm. It should be feasible to adopt OpenAPI for the request-response features of CoAP and AsyncAPI for the group comms. There's some interest in the AsyncAPI community to see CoAP support, which I'd be interested in facilitating.
> 
> Thoughts? There may be some overlap between the Link Format and Resource Directory specs, but I believe those can be mitigated - or even supported via code generation. Are there any other related efforts that should be considered? If not, there's a lot of value around the community and ecosystem of OpenAPI and now AsyncAPI.
> 
> -- 
> Jonathan Beri
> linkedin.com/in/jonathanberi
> _______________________________________________
> core mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/core

---

From: Jonathan Beri <[email-masked]>
Date: Thu, 23 Apr 2020 17:41:48 -0700

Thanks Carsten, I plan to attend! Given the short notice I doubt I'll be
able to add to the agenda (or have slides in time,) but I hope to connect
with the RG.

On Thu, Apr 23, 2020 at 4:08 PM Carsten Bormann <[email-masked]> wrote:

> Hi Jonathan,
>
> questions like this are being actively discussed in the T2TRG under the
> name of "WISHI" (Work on IoT Semantic/Hypermedia Interoperability,
> http://wishi.space).
> > I believe it would provide an improved developer experience for the
> reasons listed above to have an API specification format for CoAP and
> groupcomm. It should be feasible to adopt OpenAPI for the request-response
> features of CoAP and AsyncAPI for the group comms. There's some interest in
> the AsyncAPI community to see CoAP support, which I'd be interested in
> facilitating.
> >