6 ms·

AsyncAPI – OpenAPI-like specification for event-driven architectures

172 points by derberg 7y ago

sktrdie 7y ago
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.
- jsdalton 7y ago
  There appears to be far more details on the main website: https://www.asyncapi.com/ https://www.asyncapi.com/ Not sure why the Github repo was submitted.
  - augusto-moura 7y ago
    Websites can be embellished and misleading, also don't give a real sense of popularity and community support. I think a github repo is a thousand times better than a well "designed" landing page
    - verdverm 7y ago
      I'd like to see an example on either landing point, both preferably.
- makstaks 7y ago
  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 7y ago
    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 7y ago
      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
- carapace 7y ago
  Yeah, a "Related Work" section would (potentially) be very reassuring. What would be really cool is if this could serve as a front-end to e.g. SPIN model checker ( https://en.wikipedia.org/wiki/SPIN_model_checker https://en.wikipedia.org/wiki/SPIN_model_checker https://en.wikipedia.org/wiki/Promela https://en.wikipedia.org/wiki/Promela )
dsun180 7y ago
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 7y ago
  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 7y ago
    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 7y ago
      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.
z0mbie42 7y ago
Adding YAML to a problem will always make it worst.
- verdverm 7y ago
  https://cuelang.org https://cuelang.org has something to say about this
  - Mazzen 7y ago
    Their slogan is catchy but breaks bad in (my) mobile view
    - Mazzen 7y ago
      Documentation is also clearly expecting the user to read the page on a desktop device. If you are part of the project, please check it out. Interesting concept!
      - verdverm 7y ago
        They are using an older version of https://docsy.dev https://docsy.dev for their docs site. How does this one look on mobile? https://docs.hofstadter.io https://docs.hofstadter.io I just started that yesterday from the most recent docsy.
  - HighlandSpring 7y ago
    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?
the_arun 7y ago
What about gRPC?
- derberg 7y ago
  you mean Protobuf or what exactly?
  - CameronNemo 7y ago
    protobuf is just the serialization format gRPC is the replacement for HTTP and presumably asynchronous HTTP requests. Still not sure what their point is.
- CameronNemo 7y ago
  capnproto RPC actually supports some interesting features related to asynchronous execution: https://capnproto.org/rpc.html#time-travel-promise-pipelining https://capnproto.org/rpc.html#time-travel-promise-pipelinin...
- fmvilas 7y ago
  If you mean protobuf, here's a link to the discussion on why it wasn't included in v2.0.0. That said, we'll explore adding non-JSON formats (like XSD and protobuf) to the specicification this year.
- ronmex 7y ago
  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 7y ago
    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.
jayd16 7y ago
So is this specifically for stateless event messages? I don't really understand how you would define required state or conditional message validity.
newprint 7y ago
How this is different from Rx and Reactive Streams[1] https://www.reactive-streams.org/ https://www.reactive-streams.org/ ?
- cogman10 7y ago
  This is the difference between inner application and external application. So, similar difference between a Dictionary and a Database.
redsparrow 7y ago
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 7y ago
  Waleed is awesome. I wonder why he didn't call it asyncapi-waleedator though :P
ryanmarsh 7y ago
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 7y ago
  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!
yingw787 7y ago
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!
benatkin 7y ago
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/
superfreek 7y ago
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.
antback 7y ago
Anybody knows the main differences with https://cloudevents.io/ https://cloudevents.io/?

172 points by derberg 7y ago

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.

jsdalton 7y ago
There appears to be far more details on the main website: https://www.asyncapi.com/ https://www.asyncapi.com/ Not sure why the Github repo was submitted.
- augusto-moura 7y ago
  Websites can be embellished and misleading, also don't give a real sense of popularity and community support. I think a github repo is a thousand times better than a well "designed" landing page
  - verdverm 7y ago
    I'd like to see an example on either landing point, both preferably.
makstaks 7y ago
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 7y ago
  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 7y ago
    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
carapace 7y ago
Yeah, a "Related Work" section would (potentially) be very reassuring. What would be really cool is if this could serve as a front-end to e.g. SPIN model checker ( https://en.wikipedia.org/wiki/SPIN_model_checker https://en.wikipedia.org/wiki/SPIN_model_checker https://en.wikipedia.org/wiki/Promela https://en.wikipedia.org/wiki/Promela )

dsun180 7y ago

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 7y ago
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 7y ago
  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 7y ago
    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.

z0mbie42 7y ago

Adding YAML to a problem will always make it worst.

verdverm 7y ago
https://cuelang.org https://cuelang.org has something to say about this
- Mazzen 7y ago
  Their slogan is catchy but breaks bad in (my) mobile view
  - Mazzen 7y ago
    Documentation is also clearly expecting the user to read the page on a desktop device. If you are part of the project, please check it out. Interesting concept!
    - verdverm 7y ago
      They are using an older version of https://docsy.dev https://docsy.dev for their docs site. How does this one look on mobile? https://docs.hofstadter.io https://docs.hofstadter.io I just started that yesterday from the most recent docsy.
- HighlandSpring 7y ago
  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?

the_arun 7y ago

What about gRPC?

derberg 7y ago
you mean Protobuf or what exactly?
- CameronNemo 7y ago
  protobuf is just the serialization format gRPC is the replacement for HTTP and presumably asynchronous HTTP requests. Still not sure what their point is.
CameronNemo 7y ago
capnproto RPC actually supports some interesting features related to asynchronous execution: https://capnproto.org/rpc.html#time-travel-promise-pipelining https://capnproto.org/rpc.html#time-travel-promise-pipelinin...
fmvilas 7y ago
If you mean protobuf, here's a link to the discussion on why it wasn't included in v2.0.0. That said, we'll explore adding non-JSON formats (like XSD and protobuf) to the specicification this year.
ronmex 7y ago
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 7y ago
  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.

jayd16 7y ago

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

newprint 7y ago

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

cogman10 7y ago
This is the difference between inner application and external application. So, similar difference between a Dictionary and a Database.

redsparrow 7y ago

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 7y ago
Waleed is awesome. I wonder why he didn't call it asyncapi-waleedator though :P

ryanmarsh 7y ago

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 7y ago
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!

yingw787 7y ago

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!

benatkin 7y ago

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/

superfreek 7y ago

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.

antback 7y ago

Anybody knows the main differences with https://cloudevents.io/ https://cloudevents.io/?