Search code examples
websocketopenapispecificationsasyncapi

How do you formally describe your Websocket API?

REST and other synchronous API are well defined via OpenAPI specification, and docs&code can be generated with Swagger or other platforms. It is not suited to describe Websockets.

This question has already been asked 6 years ago on stack, and i would like to know the current status of your websocket API and their documentation.

AsyncAPI has been designed to define asynchronous API, but it does not seems well suited to websocket, it seems more oriented to publish/subscribe protocols like MQTT.

For reference, trading platforms defines public websocket API :

Solution

  • Disclaimer, I'm one of the AsyncAPI maintainers

    Actually for both APIs that you mentioned I created experimental AsyncAPI documents:

    Many folks use AsyncAPI for WebSocket. In short:

    • if your API enables multiple connections on multiple paths for multiple independent UI views, then everything is there
    • if your API is websocket but there is just one connection, and then you have some "subprotocol" used, like you connect to websocket, then you send "subscribe" message to start getting some specific messages - for that case you need support for marking request/reply. This is not in place yet, but for that you have specification extensions. Also worth noticing is that in few months we release 3.0 spec version with native req/rep support.

    Feel free to join https://asyncapi.com/slack-invite and ping me there in "specification" channel. I would love to help.