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

2

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.

2
  • Based upon your experience : Do you have any recommendation on where to store the asynchapi.yaml, the openapi.yml and the schema-file(s). Do you use a schema-registry or store them all in the same repository with local references? What schemaFormat are you using? A gist showing an example would be awesome. @observer
    – McBeelen
    Commented Jun 13 at 9:56
  • Yes, we store them all in the same repository (with shared models living in a dedicated folder, so it's easy to spot that they are under shared use) and use local references.
    – observer
    Commented 2 days ago

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.