search

sa-mw-dach / opendj

Apply Open Source principles to the Dance Floor! MOVED TO https://github.com/opendj/opendj
https://github.com/opendj/opendj
GNU General Public License v3.0
6 stars 9 forks source link

How to describe event bus interfaces? #24

Closed wrichter closed 5 years ago

wrichter commented 5 years ago

For HTTP interfaces, we can use a Swagger/OpenAPI definition, which can be rendered into a Test UI and used for scaffolding of implementations and client code. Can we use something equivalent for event bus based interfaces(#16)?

wrichter commented 5 years ago

In today's integration quarterly update, they pointed to https://www.asyncapi.com

DanielFroehlich commented 5 years ago

It is not only event bus interfaces, but interfaces in general. How do we describe interfaces?

DanielFroehlich commented 5 years ago

GRPC / Protobuffers could also be an option. Nice lean, and async is easy, simple one way rpc call with no response, ore even a stream of events as response back

https://grpc.io/docs/guides/

OpenAPI vs. gRPC comparison: https://medium.com/apis-and-digital-transformation/openapi-and-grpc-side-by-side-b6afb08f75ed

wrichter commented 5 years ago

I find gRPC interesting, Do you know the extent of gRPC Support in the RH Toolchain? Wrt event/AsyncAPI interfaces, I think AsyncAPI is a better representation than a one-way gRPC since it has a native concept of topic spaces.

DanielFroehlich commented 5 years ago

I have no clue. @ortwinschneider maybe? My understanding is that it uses HTTP/2 as transport, and good news - THAT is supported ingress with OpenShift V3.11: https://access.redhat.com/solutions/2274201

wrichter commented 5 years ago

OpenAPI should be independent of a transport protocol version, so I believe HTTP/2 should also work for an HTTP interface defined via OpenAPI. Reading about this, a new aspect came to my mind - how to describe WebSocket interfaces?? This is likely not gRPC (since we cannot expect browsers to have support for it), but also not HTTP Verbs/status codes either (so OpenAPI is maybe not a good fit: https://github.com/OAI/OpenAPI-Specification/issues/523)

DanielFroehlich commented 5 years ago

I tried to use OpenAPI to create the analysis model. From that experience: I don't like OpenAPI. It is far too fixed on REST and HTTP, so probably not suitable to describe event bus interfaces.

I will now experiment with PlantUML: use good old interfaces for sync interactions, and classes describing async events. That did work already in a white board session with @ortwinschneider, so let me try to get code it....

wrichter commented 5 years ago

Have you looked at AsyncAPI yet?

DanielFroehlich commented 5 years ago

Let me start an assessment of the Option "AsyncAPI" so we can later copy/paste to an architectural decision document. Please edit this note as desired!

Option: "Use Async.API"

AsyncAPI is an extension/variation of OpenAPI by adding async/event handling capabilities. Details here. The Getting Started doc is a quick read while providing good overview.

Pro:

  1. open to different protocols (websockets, kafka, amqp, mqtt)
  2. very close to OpenAPI, that we will probably use for sync interfaces. We could e.g. re-use schemas for objects that appear on both sync and async apis.
  3. potential future support in RH tooling (currently under evaluation). The slides for this summit talk might give additional insights (did not manage to attend it).
  4. also makes suggestions how to structure topics for events, which could be used independent of the API description format/tools

Contra:

  1. It is currently Version 2.0.0-rc1, so this is the bleeding edge of technology.
  2. Small Community - github project has only 9 members
  3. limited tooling support, VSCode extension "openapi-lint" provides limited validation capabilities, but only for V1.2.0.

Open Questions:

  1. I think we should experiment with this, e.g. define a simple async api, use it to generate prducer/consumer code against kafka and see how it works.
DanielFroehlich commented 5 years ago

Option: "Use PlantUML"

Description

PlantUML can be used to describe async events. High level in e.g. a component diag could look like this:

highlevel

On a more fine grained level, it could look like this: highlevel

Pro:

  1. no new tool, we use plantuml already

Contra:

  1. nothing can be generated out of this.
  2. current design does not include topic space, only event/message format.

Open Questions

  1. Unclear if multiple event types can be aggregated to an "interface description".
wrichter commented 5 years ago

Edit: Did add some aspects to the evaluations above

DanielFroehlich commented 5 years ago

I vote for a combination: we go with AsyncAPI where possible, and if the interface is still to vague, we go with PlantUML or simply textual description