
AsyncAPI – OpenAPI-like specification for event-driven architectures - derberg
https://github.com/asyncapi/asyncapi
======
dsun180
I would love if the definition of websockets would be added to OpenAPI
[https://github.com/OAI/OpenAPI-
Specification/issues/523](https://github.com/OAI/OpenAPI-
Specification/issues/523)

~~~
BerislavLopac
What would be the advantage of that? OpenAPI is designed for HTTP-based APIs;
I'm sure an equivalent can be done for WebSockets?

~~~
dsun180
I would be able to document websockets side by side with "normal" requests and
then use the same tooling for code generation or validation.

~~~
KMag
That use case would seem to be better served by creating a new standard that
references the other standard for its IDL and serialization format, and
general semantics, while having a separate standard for any websocket-specific
details.

That avoids having to amend the original standard for each new variation. If
you get enough variants (probably in the neighborhood of 2-4), then it makes
sense to go back and supersede the original standard by breaking out the high-
level layers each into their own standard that's designed for inclusion in
other standards. That way, for instance, your async-Bluetooth standard doesn't
have to refer to any document that gets bogged down in HTTP/1.1-specific
messaging semantics. It's not worth re-factoring your standards stack the
first time you reuse a standard, but you don't want some big spaghetti tangle
of standards, either.

------
sktrdie
We already have lots of languages for describing event-driven applications
such as Message Sequence Charts, Statecharts as well as a myriad of other
types of specifications languages part of UML but also simple DSL syntax.

Why reinvent the wheel? What does this add to the current state of the art? I
can't even find a "Related Work" section on their site.

~~~
makstaks
The idea itself is sound, having an agreed specification allows others to
build tools around this specification. (i.e. auto-generation, integration). In
theory, this makes development easier. OpenAPI achieved this and is now widely
used in various tools including Amazon API Gateway.

The types of diagrams you listed above are great for describing software in
useful ways, but none of them are rigid enough to spec out an async API.

I still need to review this spec to fully understand it, so I'm not promoting
AsyncAPI. I like the motivation behind it.

edit: typo

~~~
MuffinFlavored
I don't quite get it. Why can't I just enforce schema validation in my pub/sub
handlers?

I see the YAML example completed here: [https://www.asyncapi.com/docs/getting-
started/servers/](https://www.asyncapi.com/docs/getting-started/servers/)

    
    
        asyncapi: 2.0.0
        info:
          title: Hello world application
          version: '0.1.0'
        servers:
          production:
            url: broker.mycompany.com
            protocol: amqp
            description: This is "My Company" broker.
        channels:
          hello:
            publish:
              message:
                payload:
                  type: string
                  pattern: '^hello .+$'
    

This looks like a thin wrapper around sending a message to a message queue.
What's the gain?

Where do you define what to do as a subscriber?

~~~
derberg
you have 2 operations in the spec, publish and subscribe.

above example already tells you what to do as a subscriber, as the document
you shared describes an application that publishes a message

------
z0mbie42
Adding YAML to a problem will always make it worst.

~~~
verdverm
[https://cuelang.org](https://cuelang.org) has something to say about this

~~~
HighlandSpring
This looks vaguely relevant so figured I'd ask the question here.

I'm working on what can be pretty well reduced to an AST builder. I have nodes
of certain types which come with a set of relevant properties as well as the
set of types that you're allowed to nest. I'm looking for a markup language to
express these schemas so that I can generate the UI components (given parent
node X, generate a widget with a form that can be used to submit legal
children) and perform validation (given AST tree coming from the client,
validate it server-side before persisting it)

Currently using JSON schema but it's very verbose. Any ideas?

~~~
verdverm
cuelang is great for this, I highly recommend spending some time. It's not the
easiest to on board yet, jump in slack though and we'll be happy to help.

The project we are building on top of cuelang may be of interest:
[https://github.com/hofstadter-io/hof](https://github.com/hofstadter-io/hof)

------
yingw787
This is really interesting. I only knew of OpenAPI, but my project's going to
have both HTTP / REST APIs and WebSockets. I didn't even know this existed.
Thanks so much for sharing!

------
ryanmarsh
It's wild that this has been around since at least the middle of last year. I
went searching for a way to define service boundaries for event driven systems
and settled on a YAML structure that looks very similar.

I ended up trashing it and going for something more fluent, which I think
could easily generate AsyncAPI YAML. Maybe I'll add that to the list of issues
on my little side project.

~~~
fmvilas
It's been around for 3 years already hehe! And yes, crafting my own format was
how it all started. Happy to hear more about your project!

------
benatkin
Perhaps GraphQL could be used instead for some use cases. It's already got a
specification that's been in use for several years, and has an execution model
that goes beyond the basic request/response model.
[https://graphql.org/learn/execution/](https://graphql.org/learn/execution/)

------
redsparrow
Shameless plug: A guy on my team wrote a Node.js library for validating
messages against an AsyncAPI spec.

[https://github.com/WaleedAshraf/asyncapi-
validator](https://github.com/WaleedAshraf/asyncapi-validator)

~~~
fmvilas
Waleed is awesome. I wonder why he didn't call it asyncapi-waleedator though
:P

------
superfreek
[http://open-rpc.org/](http://open-rpc.org/) is another OpenAPI-like
specification for JSON-RPC based architectures.

JSON-RPC is simple, transport agnostic, can support any transport like
Websockets, HTTP, even PostMessage.

------
the_arun
What about gRPC?

~~~
ronmex
I'm surprised many people don't understand your comment - I had the same
thoughts. gRPC provides a very nice way to describe event driven microservices
using their "stream" keyword. It allows the implementation to be async,
blocking, or future based. You get access to a very rich ecosystem such as
bazel's grpc \ proto rules, junit rules, grpc-web for streaming to the
browser, out of the box support from istio / envoy, etc.

~~~
fmvilas
You're right. My fault here. It should actually be possible to define a gRPC
streaming API (never tried). The only missing thing for me is the protobuf
compatibility though.

------
antback
Anybody knows the main differences with
[https://cloudevents.io/](https://cloudevents.io/)?

------
jayd16
So is this specifically for stateless event messages? I don't really
understand how you would define required state or conditional message
validity.

------
newprint
How this is different from Rx and Reactive Streams[1] [https://www.reactive-
streams.org/](https://www.reactive-streams.org/) ?

~~~
cogman10
This is the difference between inner application and external application.

So, similar difference between a Dictionary and a Database.

