Repository navigation
Supporting multiple transfer protocols with OpenAPI #777
Description
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
Activity
darrelmiller commentedon Sep 2, 2016
The REST architectural style is protocol agnostic, OpenAPI isn't. More thoughts on the issue here #523
kasun04 commentedon Sep 3, 2016
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:
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 commentedon Sep 3, 2016
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 commentedon Dec 20, 2016
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 commentedon Dec 20, 2016
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 commentedon Feb 1, 2017
I am hoping #878 addresses this.
fehguy commentedon Feb 7, 2017
see #878
fmvilas commentedon May 16, 2017
@kasun04 you might be interested in the AsyncAPI specification: asyncapi.com.
MikeRalphson commentedon Jan 23, 2019
@darrelmiller Having used it briefly recently, I think minimal work (semver minor compatible) would be needed to support CoAP in 3.x.
operationobject keys offetchandipatchfrom RFC8132 (arr, me hearties), and possiblyemptyand 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 commentedon Mar 24, 2021
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 commentedon Jul 8, 2021
@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?