Howdy!
I was pointed towards AsyncAPI by @darrelmiller.
I'm the developer lead on AutoRest which we write to generate clients for OpenAPI (2.0 right now, 3.0 very soon) in Python, C#, Java, Ruby, Go, JavaScript, Typescript, PHP, (with support for directly generating PowerShell and others on the way)
We're investigating the possibility of generating clients and services for other protocols (ie, AMQP, MTTP, JSON-RPC, etc...) for a variety of purposes. The goal would be to extend AutoRest to be able to generate code for these purposes for all the languages that we support.
Background
At the current point, AutoRest performs a 'modeling' stage in the pipeline where we generate an abstraction of the HTTP REST methods that generators use to spit out code (the CodeModel
). This enables us to have a common means to 'interpret' the OpenAPI spec and produce like clients on each of the languages (and publish the SDK for each.)
We currently use this to generate 70+ SDKs for Azure services, across 7 or so languages.
The current CodeModel
is a miserable abstraction that was the result of early developers hacking their way thru the process, with little thought to expansion or reusability.
So, we're looking at the next-generation means of supporting a better abstraction, and our initial thought was to stick to OpenAPI 3 as close as possible, with additional metadata on top of that, which would impact the code generation process.
Of course, we then started thinking about adding support for other protocols, and abstracting the thought a bit further; ideally the basic information about a given call should be reusable as possible, so that the individual generators could do the most with the least amount of effort to process the CodeModel
.
My initial thoughts (before coming to AsyncAPI) with this was to simply use OpenAPI3 and substitute out the HTTP method (POST/PUT/GET/DELETE/etc) for a scheme
:method
representation so I'd end up with things like json-rpc:notification
and json-rpc:request
and substitute out the PATH
for the routing key (aka, the Topic
)
Now, it appears that you're kinda going down a similar route; except that you've created an alternate scheme
and then referred to subscribe
and publish
(which would be just fine for me, and and probably better)
I've done a cursory examination of AsyncAPI and it seems really closely aligned with OpenAPI (duh!)
Provoking thought number one.
I was curious about how closely you've modeled things -- ie, could I add in a HTTPS
scheme and additional topic-style methods
for POST/GET/PUT/DELETE
etc and model something that was incredibly close to OpenAPI v3's REST?
Provoking thought number two.
It feels like there could be a fairly concrete unified schema that could be then further narrowed for purpose-driven schemas (like OpenAPI).
Provoking thought number three.
I saw that you've also talked about supporting other "payload format definitions" and other such things. I'd like to understand what you're thinking of here. Perhaps the concept of a larger unified schema could be useful in collecting the vast array of possibilities, while still retaining the ability to have a narrower 'profile' schema that applies to a given protocol/payload (and has all the necessary restrictions to model an API for just that) (think of it like the relationship that SGML is to HTML, XML and XAML)
Ideally, I'd like to be able to support protocols/payloads/languages as all pluggable. AutoRest's pipeline is entirely configurable to support any range of these types of things. We're probably only three good days work away from stopping it from being 'swagger-focused' and loosening it up to any kind of incremental transformation. The bit that I'm trying to solve only once is the 'unified specification definition'.
It's not even necessary that the 'unified' description be end-user usable (after all, who actually uses SGML itself, right?), but perhaps as a means to drive purpose-driven specification description languages.