AsyncAPI vs. OpenAPI: Answers to Your Burning Questions
asyncapi.com
asyncapi.com
> 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.
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.
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?
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.
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.
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.
That's OpenAPI / Swagger.
AsyncApi is that, but for message queues and the like.
* 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.
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.
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.
"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.
- create openapi file - write only functions
If so, it's super nice
Automatic generation of tests à la quickcheck.
Then, pydantic/fastapi does the YAML generation for me.
Would you mind elaborating if you know more?
[0]: https://json-schema.org/draft/2019-09/json-schema-hypermedia...
> 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.
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.
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.
> 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
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.
> 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.