AsyncAPI vs. OpenAPI: Answers to Your Burning Questions(asyncapi.com)
asyncapi.com
AsyncAPI vs. OpenAPI: Answers to Your Burning Questions
https://www.asyncapi.com/blog/openapi-vs-asyncapi-burning-questions
57 comments
> Umm, yes, there were no APIs before the 2000s. Even ignoring non-web APIs there were plenty of pre-SOAP attempts at APIs on the web. XML-RPC was created in 1998 and is the direct predecessor to SOAP.
They didn't say SOAP was the first. They said APIs have been around for a long time, and brought up an older method that's probably relatable for many as an "old" attempt.
> I'm not sure I should really put much trust in a blog post by an author that doesn't even know his own Twitter handle.
Understanding of APIs and ability to avoid typos are likely extremely unrelated.
They didn't say SOAP was the first. They said APIs have been around for a long time, and brought up an older method that's probably relatable for many as an "old" attempt.
> I'm not sure I should really put much trust in a blog post by an author that doesn't even know his own Twitter handle.
Understanding of APIs and ability to avoid typos are likely extremely unrelated.
CORBA is 30 years old. Wikipedia says first APIs are now 80 years old.
I worked on OpenAPI itself and have been working on the tooling since. I recently switched to GraphQL for a project and god damn! The GraphQL design is nearly perfect and achieves whatever OpenAPI or AsyncAPI was hoping to achieve. If you have an existing JSON over HTTP (Let's not call them RESTful) API then it's harder to switch to GraphQL, but if you have a new project and want type-safety and efficiency, you must give GraphQL a shot instead of writing "hopefully will be enforced in runtime API specs".
Is GraphQL useful to people who write a lot of custom-written JSON APIs? Things that are much more than cleanly mapping JSON to CRUD SQL?
Ie i often think of GraphQL as a DSL for translating JSON to SQL. To let the caller define the query and data needed. This looks great for SQL, but if i write a custom API with non-SQL generated data, maybe in some custom data structures, the idea of supporting arbitrary querying over my data structures seems .. difficult.
Is GraphQL applicable to more than basic SQL data querying?
Ie i often think of GraphQL as a DSL for translating JSON to SQL. To let the caller define the query and data needed. This looks great for SQL, but if i write a custom API with non-SQL generated data, maybe in some custom data structures, the idea of supporting arbitrary querying over my data structures seems .. difficult.
Is GraphQL applicable to more than basic SQL data querying?
GraphQL can do anything that a REST API can do, it's just a different interface over HTTP at the end of the day. There's nothing that particularly links it to SQL or any other data store, though some tools might add that coupling, especially if they're "schema-first".
You can write query and mutation resolvers that generically do read and write operations. The resolvers are just strongly typed functions - they take in user-provided inputs and return a defined output that users can select a subset of fields from (inputs/outputs are defined in your schema).
As long as you can access your data from your backend (whether it's in a SQL db, mongo, s3, or some custom data structure) then you can do whatever processing you want in your queries and mutations.
You can write query and mutation resolvers that generically do read and write operations. The resolvers are just strongly typed functions - they take in user-provided inputs and return a defined output that users can select a subset of fields from (inputs/outputs are defined in your schema).
As long as you can access your data from your backend (whether it's in a SQL db, mongo, s3, or some custom data structure) then you can do whatever processing you want in your queries and mutations.
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.
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.
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.
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.
so, SOAP/WSDL but for the JSON era?
> SOAP/WSDL but for the JSON era
That's OpenAPI / Swagger.
AsyncApi is that, but for message queues and the like.
That's OpenAPI / Swagger.
AsyncApi is that, but for message queues and the like.
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
Outside 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.
* 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.
let 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.
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.
would you mind sharing what you mean by auto-generated validators that get injected into the code?
I'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
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.
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.
thanks for sharing.
> 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.
"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.
Shameless plug: https://pyotr.readthedocs.io
This looks quite good.
If I understand correctly the idea is:
- create openapi file - write only functions
If so, it's super nice
- create openapi file - write only functions
If so, it's super nice
Thank you - that's exactly the idea. There is also a client version which automates calling the API's operations.
> 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.
Automatic generation of tests à la quickcheck.
Then, pydantic/fastapi does the YAML generation for me.
Pyotr takes OpenAPIs and creates both servers and clients: https://pyotr.readthedocs.io
Why is the formal spec better than prose? Tooling. Now I can flag discrepancies between the spec and the actual API automatically
seems like we should just modify the openAPI spec to support async functionality. GRPC suports async in this fashion and it's much easier to reason about and adopt in specific cases.
Yet another case of competing standards
https://xkcd.com/927/
https://xkcd.com/927/
very depends on your use case and what you want to achieve in the end. Code gen? types gen or entire app? docs only? discovery? It always all depends :)
That's what asyncAPI is, no?
A real shame JSON HyperSchema is on Hiatus -- it was a really nice entrant in the space.
I couldn’t find anything about it being on hiatus, though it hasn’t had any updates on the spec from the looks of it, assuming I have it right[0]. Though for a spec I don’t feel like that means it’s in hiatus, they tend to move slowly
Would you mind elaborating if you know more?
[0]: https://json-schema.org/draft/2019-09/json-schema-hypermedia...
Would you mind elaborating if you know more?
[0]: https://json-schema.org/draft/2019-09/json-schema-hypermedia...
Another thing was that Hyperschema never really had its own proper page and documentation. You had to go to The jsonschema page[0] to find it. It says:
> JSON Hyper-Schema is on hiatus / not currently maintained as of 2021.
> This allows the team to focus the little time they do donate on JSON Schema core and validation.
> We may revisit JSON Hyper-Schema at a later date.
[0]: http://json-schema.org/
> JSON Hyper-Schema is on hiatus / not currently maintained as of 2021.
> This allows the team to focus the little time they do donate on JSON Schema core and validation.
> We may revisit JSON Hyper-Schema at a later date.
[0]: http://json-schema.org/
We really just wanted to signal that people shouldn't expect any attention on issues or PRs raised against Hyperschema till we can make time for it. Spec work is hard ya'll
Reading through the hyperschema spec it instantly seemed like the best option with really good formalisms around discovery and of course the usual specification concerns.
Thank you for that hard work! Hyperschema is a great accomplishment already and I think (as I did before) that what will bring people to it is more tooling around it more than anything else.
Thank you for that hard work! Hyperschema is a great accomplishment already and I think (as I did before) that what will bring people to it is more tooling around it more than anything else.
Apples vs Oranges? To me, async seems like an implementation detail. Why are we comparing it with Open API which is a spec? Sorry my mind is confused.
what "async" means for you? is it just JS async/await for you? have you used Kafka, or Websocket or only writing and interacting with REST APIs?
For me Async means - non-blocking experience to the user.
In context of APIS, "async" communications means event notifications and message queues: Amazon SNS/SQS, Amazon Kinesis, Azure Event hub, Kafka, RabbitMQ etc. Anything where you send a message and don't wait for a response, unlike http.
Minor correction to what I said. Async means we do not keep someone/something waiting for response. There are so many options on the implementation as you described.
AsyncAPI is about specifying push-based APIs (which are still far less standardized imho), and not about if a HTTP endpoint processes requests asynchronously (if that's what you meant). For example, if you let clients connect to your system via WebSocket - how do you specify the format of the push messages sent over the WebSocket channel?
I _think_ the reason that the comparison with OpenAPI feels weird is because OpenAPI uses one (and only one) communication interface in REST. AsyncAPI is trying to accomplish the same thing without a consensus in communication interface. This requires that any specs are far more abstract to encompass the possible options.
But consider what OpenAPI/Swagger actually changed - it made for a singular page to tell a user (or machine) all the possible ways to interact with the service and what the shape of the requests and responses would look like. AsyncAPI is meant to do the same, but it's much harder to grok with all the various protocols generalized into unnatural-looking fields/URIs/etc.
But consider what OpenAPI/Swagger actually changed - it made for a singular page to tell a user (or machine) all the possible ways to interact with the service and what the shape of the requests and responses would look like. AsyncAPI is meant to do the same, but it's much harder to grok with all the various protocols generalized into unnatural-looking fields/URIs/etc.
This sentence seems out of place, under the "What happened to Swagger? And what is OpenAPI?" section.
> Implementing OpenTelemetry typically means instrumenting code so that it can emit monitoring information.
> This information is then aggregated in a backend system, either on-premises or through monitoring as a service provider.
Was this part of the reasoning for Linux Foundation acquiring Swagger?
[edit] - formatting
> Implementing OpenTelemetry typically means instrumenting code so that it can emit monitoring information.
> This information is then aggregated in a backend system, either on-premises or through monitoring as a service provider.
Was this part of the reasoning for Linux Foundation acquiring Swagger?
[edit] - formatting
AsyncAPI and OpenAPI are different ways of defining application programming interfaces (APIs), also commonly known as API specs. Both API specs serve a crucial role in defining and governing distributed computing systems, but AsyncAPI and OpenAPI are used for different styles of integration...
AsyncAPI as spec is good but unfortunately tooling not yet on same level as for OpenAPI yet. During small project development with it I found few things that was Ok from spec perspective but doc generator not able to render docs with those features at all. And because tooling currently only following recent version of spec on any spec update you might find that any hosted tools not works for you anymore. But of course is just matter of time then tooling will be good enough.
I have similar feelings about GraphQL. Part of why I like it so much is the tooling.
From what I gather, AsyncAPI is an event-defining tool. So you can define specifically what sort of messages is expected from a service when you communicate with it. That sounds useful.
I don't understand, though, what it has to do with Async. Most messaging is done synchronously after establishing a live connection.
Why not call it EventAPI? Or MessageAPI? AsyncAPI implies it is the opposite of what it is. This name will uniquely cause a lot of confusion.
I don't understand, though, what it has to do with Async. Most messaging is done synchronously after establishing a live connection.
Why not call it EventAPI? Or MessageAPI? AsyncAPI implies it is the opposite of what it is. This name will uniquely cause a lot of confusion.
I’ve read through the spec, and there’s not really much here that you can’t accommodate with protobuf Service definitions. I do like the provider abstraction on top of push-based messaging services, but that’s just an isomorphism for a protobuf server streaming call. Given the rock solid implementation and wide acceptance, I don’t see any reason to use this over gRPC.
Suppose you are implementing a chat server that uses websockets with plain old json payloads. You want the simple human introspectability of json if you need to debug in prod via the web console. And you have a {big | distributed | lots of juniors} team so you want some code that validates the json payloads (via jsonSchema) in the two-way contract and limits errors being pushed to prod.
As if AsyncAPI was as popular as OpenAPI ...
give it a time, it is much younger but since last year it got lots of attention
OpenAPI can be used to describe the vast majority of extant APIs in the wild today. It was build to describe APIs. AsyncAPI, like GraphQL, imagines a new ecosystem. This article constructs straw man arguments against OpenAPI without making a particularly concrete case for AsyncAPI.
The vast majority of extant public APIs in the wild today. Internally, people write a lot of services that process records from Kafka topics, SQS queues, emails, file uploads, etc. The ecosystem already exists and is in need of tooling.
> This article constructs straw man arguments against OpenAPI
I don't see that at all, and why would they? AsyncAPI is leveraging OpenAPI's status as a de facto standard tool for synchronous REST APIs to promote itself as a complementary standard tool for async APIs. It wouldn't benefit them to denigrate OpenAPI.
> This article constructs straw man arguments against OpenAPI
I don't see that at all, and why would they? AsyncAPI is leveraging OpenAPI's status as a de facto standard tool for synchronous REST APIs to promote itself as a complementary standard tool for async APIs. It wouldn't benefit them to denigrate OpenAPI.
Noone is against OpenAPI, definitely on the author, thing is that OpenAPI is just not for everything and AsyncAPI complements the rest. AsyncAPI doesn't have to imagine anything, ecosystem is already there :) MQTT,Kafka, Websocket and others were there long time before AsyncAPI. I recommend you look at the article once again.
One major drawback is the lack of Java native tooling vs e.g. Swagger/OpenAPI springdoc project. Document generation + API validation can be part of the same build, instead of having to have a separate Node toolchain and build.
Since when does API only mean "web service"? The article talks about APIs being important to "modern" software development, SOAP being an "early" example of one, in the early 2000s, etc. I mean, the Win32 API comes to mind immediately.
I think that page does a bit of a disservice to AsyncAPI. IIRC it was "OpenAPI" but for messaging.
> APIs have been around for a while. For instance, the painful Simple Object Access Protocol (SOAP) used APIs in the early 2000s, but they really started getting interesting when representational state transfer (REST) came along. REST, which used the ubiquitous HTTP protocol, was lightweight and fun to work with.
Umm, yes, there were no APIs before the 2000s. Even ignoring non-web APIs there were plenty of pre-SOAP attempts at APIs on the web. XML-RPC was created in 1998 and is the direct predecessor to SOAP.
It feels like the author of this post has no historical perspective on the technology he is trying to explain, and if he skipped all the "What is an API" preamble that would be fine, but with it there it feels like an attempt at sounding like an authority that backfired.
I tried to see who this "Jesse Menning" is, but the author link goes to a twitter page for "Jeremy Menning" that hasn't seen use in 10 years. I'm not sure I should really put much trust in a blog post by an author that doesn't even know his own Twitter handle.