News for hackers. Stuff that matters.
Re:AsyncAPI vs. OpenAPI: Answers to Your Burning Questions by pimterry on Thursday September 09, 2021 @11:53AM (#28471037)
I 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) pretty effectively. AsyncAPI is much newer though, and I think the ecosystem is still quite small, but hopefully they'll get there too eventually.

Re:AsyncAPI vs. OpenAPI: Answers to Your Burning Questions by Jasper_ on Thursday September 09, 2021 @01:45PM (#28472466)
so, SOAP/WSDL but for the JSON era?
Re:AsyncAPI vs. OpenAPI: Answers to Your Burning Questions by SideburnsOfDoom on Thursday September 09, 2021 @03:35PM (#28473725)
> SOAP/WSDL but for the JSON era

That's OpenAPI / Swagger.

AsyncApi is that, but for message queues and the like.

Re:AsyncAPI vs. OpenAPI: Answers to Your Burning Questions by mlk on Thursday September 09, 2021 @11:37PM (#28477547)
SOAP 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