search

zalando / restful-api-guidelines

A model set of guidelines for RESTful APIs and Events, created by Zalando
https://opensource.zalando.com/restful-api-guidelines/
Creative Commons Attribution 4.0 International
2.62k stars 384 forks source link

AsyncAPI specification #430

Closed fmvilas closed 4 years ago

fmvilas commented 6 years ago

Hi! I just came across your API guidelines and found it awesome. And what I liked the most is that you also document your events using OpenAPI schemas. I just wanted to know if you're aware of the AsyncAPI specification. It seems like a good fit for your use case and its schemas are exactly the same as OpenAPI schemas.

tkrop commented 6 years ago

@fmvilas thanks for sharing this information with us. We will have a look to it.

fmvilas commented 6 years ago

Cool! Make sure you try editor.asyncapi.org. It will be easier.

vadeg commented 6 years ago

Hi @fmvilas!

Thank you for sharing. We have discussed it and decided to try to apply this specification to some of our solutions. Will see how it fits.

fmvilas commented 6 years ago

That's great news! Let me know if you need help. We're currently setting up a core team for the AsyncAPI specification. Whatever questions you have, let me know here or on the Slack channel. We'll be glad to help!

fmvilas commented 6 years ago

If interested in generating Markdown docs, check out this package: https://github.com/asyncapi/generator/blob/master/README.md

vadeg commented 5 years ago

Research showed that AsyncAPI schema can be used with our services.

I have tested it with Nakadi event types. Event types schema almost matches to AsyncAPI with some exception. Nakadi schema support more data types rather than AsyncAPI schema. As far as I understand this can be extended.

There is no http/https scheme support. This is not a blocked and will be fixed soon.

There are several with parser which does not allow to build schemes using streams. Only schema with topic works fine. There is also some problems with error notifications in online editor (the problem also comes from parser).

In general I think AsyncAPI schema can be applied.

P.S. @tkrop please update this ticket if I missed some points.

ePaul commented 5 years ago

Idea for a first use case:

vadeg commented 5 years ago

Version 1 of Async API has been investigated and tested. There were some questions regarding fields semantics and limitations in Async API v1 such as:

  1. Rename scheme field in Server Object to protocol because protocol describes better what is this field actually about.
  2. Allow to specify custom protocols in scheme field. Async API v1 allows to specify protocols only from predefined list.

A feature request was created do discuss questions mentioned above. @fmvilas pointed that there will be version 2 released soon which solves second issue. First issue have been solved in v2 also.

In summary, I would recommend to wait until Async API v2 will be released, refine our internal document and discuss it again.

tfrauenstein commented 5 years ago

here, the summary document of our discussion based on AsyncAPI V1 https://docs.google.com/document/d/1MJRFZwMTwjWE-cz5AFYOTqaN96fqf8OLNAunp2IhKVg/edit#heading=h.l9hrm1wom4lh

ePaul commented 5 years ago

Guild Meeting 2019-09-10

Possible approach:

Alternative:

But:

We'll discuss with the Nakadi team how to proceed here.

ePaul commented 4 years ago

Waiting until after Black Friday.

zeitlinger commented 4 years ago

Waiting until after Black Friday.

the answer to life the universe and everything

ePaul commented 4 years ago

Meeting at 2020-02-11

We currently can't give any priorities to this topic (e.g. Nakadi integration), so we are closing it for now.