Supporting multiple transfer protocols with OpenAPI

[kasun04]

Hi,

We have a requirement to extend the OpenAPI definition to support protocols other than HTTP/s and WebSockets. Given that REST is protocol agnostic, we can use OpenAPI to define any REST API implemented on protocols such as MQTT, CoAP, JMS, File etc.

We should be able to achieve this with extending 'schemes' in the current specification.
Any thoughts on already existing extension points in the current specification to facilitate above requirements?

Thanks,
Kasun

[darrelmiller]

The REST architectural style is protocol agnostic, OpenAPI isn't. More thoughts on the issue here #523

[kasun04]

Thanks, @darrelmiller .
However, OpenAPI's main objective seems to 'standardizing on how REST APIs are described' (and tight coupling to HTTP, seems to be just an implementation detail). In that case, we may have to consider:

• HTTP 2/WebSockets : Server-Push (HTTP 2 will be heavily used in the future for APIs, along with server-push)
• Pub-Sub messaging patterns with MQTT,Kafka, JMS etc.

I think, having support for the above will make OpenAPI a real powerful spec. Following requests also shows us that API definition is something beyond HTTP 1.x.

Sec-WebSocket-Protocol : synapse(contentType='application/json')
#777

Swagger for Server Sent Events
#396

WebSockets
#523

MQTT
#553

Meta-Issue
#586

[darrelmiller]

I know that's what it says, but in reality, it doesn't really mean REST. REST requires hypermedia, self-description and no out-of-band coupling, where application semantics are conveyed using the application protocol, media types and link relations.

OpenAPI's use of the term REST is the marketing version where everyone really means mostly JSON over HTTP. That's ok because the term REST has been so badly misused over the last 10 years that most people don't actually mean REST when they say it and we have got used to what they actually mean. But that doesn't mean that you can dig up fundamental principles of actual REST and try and apply them.

As I have said before, if you want a protocol independent API description language then you should look into WSDL and IDL. It is a much more complex and challenging problem to try and solve.

I addressed the WebSockets, SSE, Webhooks, long polling issues here

[woobagooba]

Greetings

CoAP transport and CBOR payload encoding has significant traction in constrained RESTful programs (IoT). Over simplifying a bit, but each is largely a binary encoding of their HTTP and JSON counterparts (respectively). Is anyone working on OpenAPI support for CoAP/CBOR? Search so far come up empty. Cheers

[darrelmiller]

There is no work ongoing to support CoAP, to my knowledge. We have may requests to support many different protocols, but our primary focus is completing the OpenAPI V3 for describing HTTP APIs.

If it is largely a binary encoding of HTTP and JSON, what parts of OpenAPI's description of HTTP and JSON are insufficient to describe a CoAP API?

[fehguy]

I am hoping #878 addresses this.

[fehguy]

see #878

[fmvilas]

@kasun04 you might be interested in the AsyncAPI specification: asyncapi.com.

[MikeRalphson]

If it is largely a binary encoding of HTTP and JSON, what parts of OpenAPI's description of HTTP and JSON are insufficient to describe a CoAP API?

@darrelmiller Having used it briefly recently, I think minimal work (semver minor compatible) would be needed to support CoAP in 3.x. operation object keys of fetch and ipatch from RFC8132 (arr, me hearties), and possibly empty and support for the 7XX response key and a bit of language cleanup. Is there any appetite for a PR on this subject?

/cc @woobagooba @cbornet - refs #553

[ondrejtomcik]

If it is largely a binary encoding of HTTP and JSON, what parts of OpenAPI's description of HTTP and JSON are insufficient to describe a CoAP API?

@darrelmiller Having used it briefly recently, I think minimal work (semver minor compatible) would be needed to support CoAP in 3.x. operation object keys of fetch and ipatch from RFC8132 (arr, me hearties), and possibly empty and support for the 7XX response key and a bit of language cleanup. Is there any appetite for a PR on this subject?

/cc @woobagooba @cbornet - refs #553

I am using openapi3 for describing CoAP APIs. Actually, the only thing I miss is support for OBSERVE operation, so it's clearly documented that OBSERVE on a resource is supported as well. Yes, actually it's GET with an option, but to visualize if it's supported or not I would model it as a separate op.

@MikeRalphson did you work on this subject?

[woobagooba]

@ondrejtomcik I would like to learn more about how you are using 3.0 to spec CoAP interfaces, Handling of CON/NON messaging, response codes, etc. Can you provide a sample API?