Follow up for OpenAPI-Specification/#55

[bali182]

Hello! As a suggestion from @fmvilas raised in OAI/OpenAPI-Specification#55, I thought I open a discussion here. With anything I say, I mean no disrespect, nor do I expect the course of AsyncAPI to change, it's just my opinion.

TLDR of the story: I raised a proposal for OpenAPI to include websockets (can be found here: OAI/OpenAPI-Specification#2881). It very closely resembles some parts of the current AsyncAPI spec. The reason for this, is that a few weeks ago I found the roadmap of AsyncAPI. In this roadmap the idea of supporting basically "every" possible method of communication was really unappealing to me, this is why I suggested adding just a bare-bones, framework-free websocket protocol description in OpenAPI.

@fmvilas suggested I expand on what I don't like in the roadmap, and why it made me look for other alternatives.

I look at this from the point of view of a client/frontend dev, who really dislikes using either http or socket apis without formal spec. Because of this, take what I say with a grain of salt, as I haven't used 80% of the currently available bindings, I don't even know what some of them are. For my job the 2 available "low level" protocols are http (this is fully and fairly decently covered by OpenAPI) and websockets (for which I'm looking for the right solution).

When I started looking at AsyncAPI, to effectively generate code (which is my goal) was only blocked by one small thing, which I raised here: (asyncapi/spec#613). For this there is already a proposed solution out there. But the discussion around this made me look at other issues/proposals.

To name a few:

• Support request/reply pattern spec#94
• Proposal to solve publish/subscribe confusion spec#618
• Proposal to allow defining schema format other than default one (AsyncAPI Schema) spec#622

As far as I have seen they are all serving a purpose, and make the spec more useful for a certain purpose. But also make an already complex spec even more complex, difficult to understand, write, and generate from correctly. As I said in the previous conversation, I fully respect the goals of AsyncAPI. But in my opinion trying to express so many different protocols and frameworks is never going to be idiomatic for all (please prove me wrong :) ).

If we take a step back, and look at a well written OpenAPI schema, you can read it without looking much into the specs, by just knowing the HTTP protocol. With AsyncAPI I spend more time reading docs or proposal notes rather than the schema itself to try and understand what I'm looking at (even just for simple hello world examples).

To finish & to summarize, the 2 main reasons I'm looking at alternatives to AsyncAPI (and I raised the idea of including sockets in the OpenAPI spec):

• Complex schema, which is getting more complex.
• Open issues make it look like there are many breaking changes incoming.

[jonaslagoni]

Thanks for the feedback!

Complex schema, which is getting more complex.

Can you be more specific as to what you find complex for your use case? 🙂

[fmvilas]

Thanks a lot for starting the discussion, @bali182. Don't worry about giving negative feedback, that's what ultimately makes us grow :)

As far as I have seen they are all serving a purpose, and make the spec more useful for a certain purpose. But also make an already complex spec even more complex, difficult to understand, write, and generate from correctly.

With AsyncAPI I spend more time reading docs or proposal notes rather than the schema itself to try and understand what I'm looking at (even just for simple hello world examples).

I totally get it. When I created the roadmap, I made sure we had three goals which, at first, may seem random or not connected but they're actually more related than some people think:

1. AsyncAPI unifies all the API specifications: This is what makes things possible.
2. API development experience is seamless: This is what makes things easy to use.
3. The AsyncAPI community grows 400%: This is what makes things sustainable in the long term.

OpenAPI, GraphQL, and other specs, have us used to write them by hand in a code editor. While that's fine and should remain possible, the second goal is there to actually provide a different layer of abstraction, making things easier. To a degree that you don't actually need to know the spec to author AsyncAPI files or to use them (docs, code generation, etc.). Actually, long term, you should not need to know AsyncAPI, OpenAPI, GraphQL, and so on, to create an API or an EDA. That's the vision. You can compare this to PDF or XLS editing. Yeah, you can open these files in a code/text editor and start typing them. But why would you do that if you have applications that abstract you from all the complex details of the inner syntax?

I'm not trying to prove you wrong here. I just think I'm probably not doing a great job communicating the roadmap and the vision. I hope that sheds a bit more light on why I chose this direction over other alternatives (like creating multiple separated specs).

That said, with v3, a WebSocket API should actually be pretty easy to describe as soon as we introduce request/reply support. But if it doesn't end up being super easy, at least you can count on Studio (and other tools) to make it super easy for you. Hope that helps! And again, thanks a lot for opening the discussion 🙏

[bali182]

Thanks for the summary @fmvilas, in that case I'm very interested v3.

I always approach this from tool-writing point of view, but you are absolutely right, good UI tools can help a lot in adaption.

But no matter how nice an editor is, here are a few concepts that seemed overly complex to me (this is also to answer to your question, @jonaslagoni):

• The traits. If I understand this correctly this promotes code reuse. However, it makes figuring out (even when just reading the document) what comes from where much more complex. Not to mention tooling, where if I understand it correctly traits have to be merged with the actual object they support.
• The relationship between objects in this proposal: Proposal to solve publish/subscribe confusion spec#618. This took me around 15 minutes, until I understood the small, to the point example. In most cases where we reference other parts of the schema we go from larger concept to smaller. Here we go the other way. If I were to read this without explanation of what's the goal, I think I'd be in trouble.
• Schema format in Proposal to allow defining schema format other than default one (AsyncAPI Schema) spec#622. I understand the purpose, but this brings the same ambiguity to AsyncApi as we have at OpenAPI, when the schema/content is not expressible using json schema, if I understand the idea correctly. This makes tooling behaviour ambiguous again, and I can't think of a scenario, where UI editors can help here.

Still, I will definitely give v3 a try! And even though I'm complaining, I'm very thankful for you guys working on the spec, and trying to lift socket and other communication protocols out of the stone age where nobody has any idea what is being sent/received :D