Missing primer and/or deeper intro

[clemensv]

The spec is generally rather light on explaining the motivation for the spec itself and for its elements. I don't think pointing to OpenAPI is sufficient.

OpenAPI has a fairly straightforward job: Define a set of operations that are immediately realized by a (synchronous) web service implementation and exposed to an application via proxy code.

AsyncAPI, as I see it, has a more complicated job because it defines flows that involve intermediaries which may not be in control of the API implementation owner, and potentially multiple layers of such intermediaries, and that requires quite more elaboration to achieve interoperability.

For instance, let's consider a backend service in a retail scenarios that sits behind a queue and that understands three different messages. The messages originate from a point-of-sale system and are initially queued up in an on-premises system and then replicated into the backend system with some sort of shovel. That is quite common.

How does the security section in the AsyncAPI map to such a scenario? The backend service API owner is likely neither in control of securing the broker-to-broker integration flow from the on-premises queue to the backend queue, and it's definitely not in control of how the mobile front-end device interacts with the on-premises broker. Does each layer have its own AsyncAPI document that refers to a shared base document?

The security section's discussion around scopes, with the "write:pets" and "read:pets" examples, also seems to imply that there are application-specific authorization rules being defined here, but how does that work through two layers of middleware?

I also think that AsyncAPI needs to take a much stronger stance on correlated multi-directional flows; I believe that is the niche where the spec can really fill a gap. There are plenty of specs that define schemas for messages and events abstractly (not the least CloudEvents in CNCF), but there's a real gap in defining multi-directional conversations abstractly: Not just request/reply, but also scatter/gather patterns, saga patterns, etc.

How does a typical sequence diagram describing a multi-directional conversation between four parties map to an AsyncAPI document?

[fmvilas]

I'm not sure I fully understand your point here. Currently, AsyncAPI defines what an application expects on a set of given communication channels. It is application-centered and therefore we don't care about the topology. This way of defining communication has drawbacks but we're working on them primarily at #390 (and related issues at #520). Most probably, a version 3 of AsyncAPI would define what an application does as opposed to what an application expects. This way, a 4-layer system can be described using 4 different AsyncAPI files (one per application/middleware).

How does a typical sequence diagram describing a multi-directional conversation between four parties map to an AsyncAPI document?

Using multiple AsyncAPI files, one per party.

---

That said, and given your experience, would you mind opening a proposal with a clear solution of how to fix the problems you're concerned about? That'd be helpful.

[derberg]

so far based on the initial description I think you might think of:

• kinda spec like https://github.com/serverlessworkflow/specification/blob/main/specification.md that btw soon will release 0.7 and support AsyncAPI
• or library like https://github.com/asyncapi/app-relations-discovery that can consume multiple AsyncAPI files and draw an architecture diagram of flows (except it is not able to guess a sequence but just show relations)

[clemensv]

Using multiple AsyncAPI files, one per party.

I believe that's leaving the key opportunity on the table.

That said, and given your experience, would you mind opening a proposal with a clear solution of how to fix the problems you're concerned about? That'd be helpful.

We are still interested, but in spite of the LF press releases, the governance model and the effective copyright are not yet in a place where we could take the pen.

[fmvilas]

Alright, let me check again with LF and I'll get back to you.

[iancooper]

@clemensv I think that what AsyncAPI does well is provide a way to document Address, Binding and Contract for an endpoint, in a producer or consumer role. In that sense its goals are not dissimilar to something like WCF, and the notion of being able to create infrastructure from the definition, or scaffold consumer applications is quite powerful, it's just platform neutral.

Some things are gaps. It is difficult to see flow. if service A receives a discrete message foo and in response issues a discrete message bar, there is no way to understand that connection, let alone if the emission of bar is conditional and it might equally well result in boz or baz. The inability to see "how things flow" is a big limitation in lots of enterprises which leads to folks struggling to reason about failure paths etc.

Being able to see flow more clearly would fill an important gap.

There is also the slightly more complex idea that service B produces stream qux, and service C produces stream thud and a another service combines them in garply which service E consumes how do we show that flow, such that we can see that service E depends on the flow from B and C, not just D.

The growth of streams that flow into each other after being combined with something like KSQL represents a real blind spot for many enteprises, and it would be useful to be able to document and perceive it more easily.

[smoya]

Describing workflows through the spec has been lightly mentioned here. https://serverlessworkflow.io is there for that reason and you can find an example in the referenced comment.

[iancooper]

@smoya This might be different to a workflow via a state machine. IMO it has more in common with flow-based programming or reactive.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️