[HN Gopher] AsyncAPI vs. OpenAPI: Answers to Your Burning Questions
___________________________________________________________________
AsyncAPI vs. OpenAPI: Answers to Your Burning Questions
Author : Lagoni
Score : 85 points
Date : 2021-09-09 11:03 UTC (11 hours ago)
(HTM) web link (www.asyncapi.com)
(TXT) w3m dump (www.asyncapi.com)
| msoad wrote:
| 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".
| lijogdfljk wrote:
| 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?
| nlarew wrote:
| 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.
| j4ah4n wrote:
| 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
| zzbzq wrote:
| 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.
| dnautics wrote:
| 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.
| panabee wrote:
| would you mind sharing what you mean by auto-generated
| validators that get injected into the code?
| dnautics wrote:
| 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.
| darepublic wrote:
| Why is the formal spec better than prose? Tooling. Now I can
| flag discrepancies between the spec and the actual API
| automatically
| soulnothing wrote:
| 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.
| SideburnsOfDoom wrote:
| > 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.
| prionassembly wrote:
| > Is there a benefit to describing APIs using YAML instead of
| just, y'know, prose?
|
| Automatic generation of tests a la quickcheck.
|
| Then, pydantic/fastapi does the YAML generation for me.
| pimterry wrote:
| 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.
| Jasper_ wrote:
| so, SOAP/WSDL but for the JSON era?
| SideburnsOfDoom wrote:
| > SOAP/WSDL but for the JSON era
|
| That's OpenAPI / Swagger.
|
| AsyncApi is that, but for message queues and the like.
| hardwaresofton wrote:
| A real shame JSON HyperSchema is on Hiatus -- it was a really
| nice entrant in the space.
| no_wizard wrote:
| 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...
| the_arun wrote:
| 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.
| dominikbucher wrote:
| 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?
| derberg wrote:
| 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?
| the_arun wrote:
| For me Async means - non-blocking experience to the user.
| SideburnsOfDoom wrote:
| 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.
| the_arun wrote:
| 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.
| dan_quixote wrote:
| 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.
| throwaway13337 wrote:
| 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.
| sigmonsays wrote:
| 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.
| dnautics wrote:
| That's what asyncAPI is, no?
| pokoleo wrote:
| Yet another case of competing standards
|
| https://xkcd.com/927/
| derberg wrote:
| 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 :)
| ducktective wrote:
| Are these specifications on how to define APIs?
| derberg wrote:
| yes, how to describe/design an API
| crad wrote:
| I think that page does a bit of a disservice to AsyncAPI. IIRC it
| was "OpenAPI" but for messaging.
| dpratt wrote:
| 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.
| dnautics wrote:
| 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.
| VenTatsu wrote:
| > When did APIs start?
|
| > 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.
| mirekrusin wrote:
| CORBA is 30 years old. Wikipedia says first APIs are now 80
| years old.
| staticassertion wrote:
| > 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.
| moron4hire wrote:
| 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.
| Thaxll wrote:
| As if AsyncAPI was as popular as OpenAPI ...
| derberg wrote:
| give it a time, it is much younger but since last year it got
| lots of attention
| ahl wrote:
| 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.
| derberg wrote:
| 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.
| dkarl wrote:
| 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.
| strobe wrote:
| 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.
| m1ckey wrote:
| I have similar feelings about GraphQL. Part of why I like it so
| much is the tooling.
| Lagoni wrote:
| 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...
___________________________________________________________________
(page generated 2021-09-09 23:01 UTC)