AsyncAPI – OpenAPI-like specification for event-driven architectures | Hacker News Reader

AsyncAPI – OpenAPI-like specification for event-driven architectures

github.com

172 pointsderberg38 comments

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.

There appears to be far more details on the main website: https://www.asyncapi.com/ Not sure why the Github repo was submitted.

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

I'd like to see an example on either landing point, both preferably.

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

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/

    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?

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

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/Promela )

Adding YAML to a problem will always make it worst.

https://cuelang.org has something to say about this

Their slogan is catchy but breaks bad in (my) mobile view

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!

They are using an older version of https://docsy.dev for their docs site.

How does this one look on mobile? https://docs.hofstadter.io

I just started that yesterday from the most recent docsy.

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?

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

I was about to argue, but then I looked at the project.

This isn't just config-file YAML.

This is programming-language YAML. :/

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!

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.

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!

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/

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.

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

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

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

What about gRPC?

you mean Protobuf or what exactly?

protobuf is just the serialization format gRPC is the replacement for HTTP and presumably asynchronous HTTP requests. Still not sure what their point is.

capnproto RPC actually supports some interesting features related to asynchronous execution: https://capnproto.org/rpc.html#time-travel-promise-pipelinin...

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.

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.

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.

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

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

This is the difference between inner application and external application.

So, similar difference between a Dictionary and a Database.

I would love if the definition of websockets would be added to OpenAPI https://github.com/OAI/OpenAPI-Specification/issues/523

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

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

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.

Reply on news.ycombinator.com