Switch backend from pure Websocket API to a REST API

[FSMaxB]

Websockets are great for one-off notifications but not for request/response style communication.

Currently most of the API is actually following the request/response pattern which means that the Frontend needs to reimplement it on top of Websockets which involves request ID tracking and timeout handling. It's a much better idea to just use HTTP for that, since it's designed to follow the request/response model.

The initial version of the REST API should:

• Model the same functionality as the current websocket API. Including a mechanism for protecting against outdated resource updates (what the MediumVersion currently provides)
• Be documented via Open API, if possible automatically generated from the backend code.
• Not replace Websockets for situations where the server contacts the client.

We're still evaluating if we stay with Gotham or switch to a different web framework for this. Web frameworks looked at:

• rocket
  • probably the most convenient and "out of the box" solution as a web framework, quite opinionated though
  • doesn't yet have builtin support for websockets
  • we weren't able to find a way to implement websocket support ourselves without forking it, this seems by design because there is no access to the underlying hyper connection type on purpose: Upgrading connection to WebSocket (perhaps using underlying hyper::Request ?) rwf2/Rocket#1703 (comment)
  • Supports OpenAPI via rocket_okapi
• gotham
  • We're already using it for the websocket API (although with manual websocket implementation)
  • Already familiar with the codebase
  • Supports OpenAPI via gotham_restful although this is kind of tacked on
  • No builtin way to do REST APIs, we would need to rely on gotham_restful mentioned above
• axum
  • Builtin support for websockets
  • Part of both the tokio and the tower universe.
  • Currently no easy way to create Open API documentation but there's an ongoing discussion about it: Support generating OpenAPI/Swagger docs tokio-rs/axum#50
• rweb
  • Builtin support for Open API
  • Builtin support for websockets
  • Based on warp, which we switched away from in the past because the compile times were unbearable (but which was awesome apart from that)

[FSMaxB]

As of #241 we've fully switched to rweb!

[simonsan]

As of #241 we've fully switched to rweb!

How are your experiences for now with rweb?

[FSMaxB]

How are your experiences for now with rweb?

@simonsan Great, until you try multiple #[data] parameters or other stuff that one would want to do. So switching to axum after all. Might have to do OpenAPI manually or implement support for it ourselves if noone else picks up the work on it.

[simonsan]

How are your experiences for now with rweb?

@simonsan Great, until you try multiple #[data] parameters or other stuff that one would want to do. So switching to axum after all. Might have to do OpenAPI manually or implement support for it ourselves if noone else picks up the work on it.

Interesting, warp directly would not be an option? If so, why have you decided against it?

[FSMaxB]

Interesting, warp directly would not be an option? If so, why have you decided against it?

We've initially been using warp actually (before gotham). The ergonomics of the Filter trait aren't too great and you can't even make a custom implementation (or if so, I haven't yet found out how). Also warp doesn't have the concept of an API, just Filters, so given that and how it works in general, I'm not sure how one could automatically create an OpenAPI API description from it without essentially writing your own Web-Framework on top of it.

Apart from the list above we also considered actix-web, but given some bad experience in the past, we decided against it (which might not have been a completely rational decision as from the things I know now, it would probably have been a great contender). But given that my current employer was using actix-web already and just recently migrated from it to axum, axum looks like an even better choice than previously because I can piggy back on my experience from work. Also the API is quite nice in terms of both being simple and powerful at the same time.

But if you want to work with generated OpenAPI descriptions right now, taking another look at actix-web and paperclip might not be such a bad idea.

[simonsan]

Funnily I'm working with warp currently, more because I tried actix-web and it didn't work well with reqwest due to some incompatibility in the async runtime. So I was stuck with warp, because I wanted to stick with reqwest due to redirects, wasm and other things. So I thought warp and reqwest might be a good combination. I will try axum for sure as well for a smaller project and take a look at the ergonomics. Thank you for you review!

[FSMaxB]

axum with automatically generated OpenAPI description is ready, see #777