Incorporating asynction into existing flask API with socketio events

[AFlowOfCode]

Hi there, this project looks really interesting & I have a question which I hope is not out of place.

I have an API in development which uses flask and flask-restx for generating an openapi spec upon which several developers are dependent in order to develop front-end applications. There is also a small set of websocket events (one path, 3 - 5 events) implemented via flask-socketio, and I am really missing the Swagger-style documentation when it comes to the socketio pieces. That ultimately led me to AsyncAPI & then asynction.

I've already missed the "spec first" boat since the code is already implemented. But I'm wondering if I should back up and incorporate asynction in order to be able to properly integrate some nice documentation.

My question is, given the fact I'm already running an operational API with some websocket events, how complicated would it be to add in asynction at this point and convert my existing events? I haven't had the chance to fully look into how things work with asynction yet, so I appreciate any thoughts about the complexity such a transition might pose. Thanks!

[dedoussis]

Hey @AFlowOfCode! Thanks for your feedback and apologies for the late response.

Asynction is built on top of Flask-SocketIO and is fully compatible with it. Essentially, the AsynctionSocketIO class (which is the entrypoint to any asynction app) inherits from the flask_socketio.SocketIO class. Asynction only adds auxiliary capabilities on top of the core functionality of FlaskSocketIO, which is left intact.

Wrt onboarding an existing API to Asynction, the main piece of work would be to come up with the actual spec of your API, which is then going to be fed into Asynction. You may find this blog post particularly helpful when attempting to model your existing SocketIO API in AsyncAPI. Once you got your spec finalised, transitioning from vanilla FlaskSocketIO to Asynction flavoured FlaskSocketIO should be relatively trivial, especially for an application involving <10 events.

A typical migration would involve:

1. Modifying the entrypoint to your FlaskSocketIO app to use the AsynctionSocketIO class instead of flask_socketio.SocketIO. In a typical Flask-SocketIO setup, this should just be replacing the class name, and passing the additional spec_path argument to the constructor.
2. Removing the now redundant @socketio decorators from your existing event and error handlers. Asynction auto-registers these handlers by inspecting the x-handler references within the spec file.

Since this is an operational API that clients currently depend on, I would strongly advise in favour of disabling validation of incoming event payloads, especially when the migration is first rolled out (see the validation parameter of the AsynctionSocketIO constructor). This would prevent existing client integrations breaking due to misdocumentation of existing event messages. Think of a scenario where an existing client arbitrarily passes additional arguments as part of the event payload. FlaskSocketIO does not care about schemata, and hence no exceptions are raised. However, Asynction may introduce a strict event schema which does not allow additional arguments. It's important to prevent breaking existing client integrations, and disabling the validation would ensure that. You may later enable the validation incrementally, starting with loose schemata and testing at pre-production environments, only promoting it to prod once you are confident that no existing integrations are to be broken.

Please take all of the above with a pinch of salt. The answer to your question vastly depends on the specifics of your application. Let me know if you would need further help. Will try to be more swift with my response times.

[AFlowOfCode]

The blog post looks very helpful. I'll close the issue as this has given me an idea of what it will take and a great starting point. Thanks for your thorough response!