4

What I try to solve:

  • Given I run a set of microservices, most of which expose a RESTful API and additionally publish or consume events via messaging broker,
  • and I have decided to go "API first" using OpenAPI and AsyncAPI to specify these APIs,
  • when I design my the domain models,
  • then ... should I create separate domain models for REST and messagin, or should I reuse the models from my REST spec within the events?

Pros and cons that I have come up with myself:

Pro:

  • If the representation of the models is the same in REST and in messaging, the clients will understand it more quickly.
  • I only need to write the spec once.
  • There are no duplicate model definitions for REST and messaging, hence they cannot accidentally deviate from each other.
  • I don't need to use the AsyncAPI generator, because all model classes are generated by the OpenAPI generator.

Con:

  • AsyncAPI allows to $reference OpenAPI models because both are based upon JSON schema, but there is no guarantee that every OpenAPI feature will be supported within AsyncAPI as well.

AsyncAPI is still quite young, so...: Is there already a general best practice?

2
  • 3
    AsyncAPI allows to $reference OpenAPI models because both are based upon JSON schema, but there is no guarantee that every OpenAPI feature will be supported within AsyncAPI as well. -- Cross that bridge when you get to it. Commented Oct 18, 2021 at 19:53
  • Yes I agree to that, it's acceptable to take that risk. But I might be missing further pros or cons in my judgement hence the question. :)
    – observer
    Commented Oct 22, 2021 at 11:15

1 Answer 1

1

Reporting our own experience so far: We have decided to share the DTO models, also based on the comment by @Robert Harvey, and this reuse has worked out well for us. AsyncAPI files always reference OpenAPI models. We only use Openapi-Generator. So far, we have not encountered any syntax problems.

Maybe this helps other readers who face the same API design decision.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.