4 ms·
Can someone tell me what the heck AsyncAPI actually does? I've had it bookmarked for a few years because it sounds relevant to the types of things I work on, a
by zzbzq 5y ago
Can someone tell me what the heck AsyncAPI actually does? I've had it bookmarked for a few years because it sounds relevant to the types of things I work on, and I often return to glance at the docs for a while.
Is there a benefit to describing APIs using YAML instead of just, y'know, prose? Seems like basically all you can do is generate HTML docs from YAML. Ok, so let me get this straight: instead of writing docs, I write YAML... --Either way I write 1 thing,--but now I can only create docs from the problem space of the known YAML schema. So it's a lossy abstraction.
Looking around I see you can now do some basic code gen of models in any language, as long as that language is python or matches the regex /java/ . But usually these messaging systems already use some data format with schemas and code gen tools like protobuff or avro! It's not just redundant, it's a collision, because something might not match up right.
Unless there's something else, it seems like something I'd advise to NOT use.
- pimterry 5y agoI think the core goal is to have one machine-readable source of truth for your API. You can write docs, the API interface, API input validation, API correctness tests, performance tests, and 10 per-language SDKs & clients all by hand, but then they very quickly get out of sync, and nobody knows which is 'right'. If you write docs as prose, good luck keeping it updated when management wants it translated into 10 languages and the API changes every week. Meanwhile, at least in theory, with a good central spec you can generate at least the docs & much of this code, or alternatively automatically validate custom implementations & real traffic to get immediate warnings if there are discrepancies. There's a lot of power in formal specifications. That is all dependent on tooling though. OpenAPI is far ahead in that respect, and can achieve this goal for most HTTP APIs & a huge list of languages (see https://github.com/OpenAPITools/openapi-generator https://github.com/OpenAPITools/openapi-generator) pretty effectively. AsyncAPI is much newer though, and I think the ecosystem is still quite small, but hopefully they'll get there too eventually.
- Jasper_ 5y agoso, SOAP/WSDL but for the JSON era?
- SideburnsOfDoom 5y ago> SOAP/WSDL but for the JSON era That's OpenAPI / Swagger. AsyncApi is that, but for message queues and the like.
- mlk 5y agoSOAP messages (unlike REST) can be sent in many ways, including message queues.This is also why IMHO SOAP seems bloated to most, it handles stuff (headers, faults, encryption etc) that REST delegates to HTTP
- soulnothing 5y agoOutside of html docs, it's purpose is similar to swagger * Auto generate mock / containers for testing * Generate server interfaces * Generate models that go across the wire * Remove boiler plate to spin up an async client, sqs, kafka etc. That being said most of the generators are from the node sides and left a bit to be desired. I also see it falling into the same issue as open api. Most places I've been dynamically generate the open api spec. I had written a JVM async/open api gradle plugin. That generated all the above. The nice thing was that if your server didn't implement the agreed upon spec it would fail to compile. Allowing for asynchronous development, back end/mobile/front end agree on the spec and can work on the feature at the same time. This can also be expanded into k6/gatling. Hit this endpoint, guarantee this sla and ensure everything functions as expected. By having the contract first, you can automate a majority of the down stream tasks. I think it has a use for contract first development, and is good in conjunction with something like avro. But it serves best in a contract first flow. Where in you define a spec, if it compiles you match the spec. Most servers don't take in a spec and define routes off operation names. Why not dynamic async api generation? A lot of the generators reflect at run time, slowing down startup, and don't provide the most human readable definitions. Also lagging behind the latest implementation, and miss potential new features.
- dnautics 5y agolet me give an example of how I wanted to use this. For fun I was working on the backend for Dogehouse (open source clubhouse clone) for a while, and for whatever reason the creator wanted the entire API to go over websockets. Ok, well, sounds like a fun thing to play around with [0]. Maintaining API consistency between the FE and BE was... very challenging, because there was very little discipline in the FE, because it was mostly into/junior programmers with not a lot of experience with API change management and feature discipline, testing, etc. So I really wanted to use AsyncAPI to create a contract between the FE and BE to be able to enforce that discipline - by auto-generating validators that get injected into the code and raise hell if invalid content is pushed by either FE or BE. It wasn't really ready for that yet at the time, but I think over time AsyncAPI will be the way to go. [0] in retrospect probably would have been better as a normal MVC app with only the chat and audio parts over ws, but... Again, not my project.
- panabee 5y agowould you mind sharing what you mean by auto-generated validators that get injected into the code?
- dnautics 5y agoI'll be open sourcing one I'm building for openApi at work in a few months, in the meantime, I have compile-time generated jsonschema validators here: https://hexdocs.pm/exonerate/Exonerate.html https://hexdocs.pm/exonerate/Exonerate.html In elixir parlance checking the schemas for REST (or in the case of asyncAPI, ws) transactions will happen based on a "plug" which injects the validation into the processing pipeline.
- panabee 5y agothanks for sharing.
- SideburnsOfDoom 5y ago> Is there a benefit to describing APIs using YAML "describing HTTP APIs using YAML" (or JSON) is OpenApi/Swagger. AsyncAPI appears to be the "OpenApi, but for message queues" (and similar async communication mechanisms). > Basically all you can do is generate HTML docs from YAML. With OpenApi, you can generate interactive docs, where you can build and execute requests against a real API (not in prod, we hope) You can generate code off OpenApi (and not just python and Java*). Anything from just DTOs to full clients. You can generate stub servers. You can inspect server code and flag up where it differs from the spec. You can test your API.
- BerislavLopac 5y agoShameless plug: https://pyotr.readthedocs.io https://pyotr.readthedocs.io
- woile 5y agoThis looks quite good. If I understand correctly the idea is: - create openapi file - write only functions If so, it's super nice
- BerislavLopac 5y agoThank you - that's exactly the idea. There is also a client version which automates calling the API's operations.
- prionassembly 5y ago> Is there a benefit to describing APIs using YAML instead of just, y'know, prose? Automatic generation of tests à la quickcheck. Then, pydantic/fastapi does the YAML generation for me.
- BerislavLopac 5y agoPyotr takes OpenAPIs and creates both servers and clients: https://pyotr.readthedocs.io https://pyotr.readthedocs.io
- darepublic 5y agoWhy is the formal spec better than prose? Tooling. Now I can flag discrepancies between the spec and the actual API automatically