Alternative API Specifications - RAML, AsyncAPI, XSD, and more

[ewinnington]

Beyond the OpenAPI OAS Specification, there exists other competing specifications with their own advantages and representations.

AsyncAPI

• https://www.asyncapi.com/docs/concepts/asyncapi-document

This is for example used to document Websocket messages.

RAML

• https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md/
• https://raml.org/

RAML is used in Mulesoft's Anypoint API Gateway, among others.

Is there a view of extending Kiota to generate clients using other specifications?

Another example of specifications would be XML XSD specifications for RabbitMQ message serializations - which is common in some trading platforms and messaging. Here I use tools to generate classes for the XML deserialization.

I understand that it is a slippery slope, because if you start adding more supports, then the question comes should it do a GRPC specification to client? This is provided by grpc tools currently - but maybe kiota could integrate with such other existing tool pipelines?

This is not a request, but I would be curious to know about what is the idea of the kiota project on this topic.

[baywet]

Hi @ewinnington
Thanks for your interest in kiota and for reaching out.

This is something we've talked about internally and intentionally left out from design documentation/public issues as we wanted to see whether there was any kind of customer demand for it.

On different description formats

If you look at Kiota's internals, you'll notice it goes through the following process to generate code

flowchart LR
     oai[OpenAPI Document] --> oainet[OpenAPI.NET representation]
     oainet --> CodeDOM
     CodeDOM --> refined[Language refined DOM]
     refined --> writers[Code Element Writers]
     writers --> code[Generated Code]

Loading

Assuming we do some heavy refactoring, we should be able to swap the first two steps to support another description format.
Another alternative would be to build/use a conversion library from that format to OAI instead of step 1.

On supporting different transport layers

Right now the abstractions layers are designed with some assumptions about an HTTP/REST transport. It might work without changes for websockets and MQTT, but we might run into major design issues.

Overall mid-term (6 months horizon) plans at this time

At this time we're still focusing on OpenAPI, adding support for 3.1 is one of our major investments in the area, completing languages support for the languages we started is another.
We also are planning for experience changes (in the way you manage API clients, etc...) which are likely to keep us busy for the next semester.
We're NOT planning to add support for different transports or description formats since there's no customer demand for it (you're the first one to bring it up really) and that'd require significant work. But discussions like those help understanding the need for it.

Additional elements

One reason that often gets cited for GRPc/GraphQL/MQTT over HTTP/REST is the performance aspect. (besides architecture differences or developer experience preferences).
One experiment we ran internally was to add serialization support for CBOR both on the client and service side. Assuming both support http2/3 we get on part throughput or sometimes better throughput with a REST API on CBOR + HTTP2/3 than other approaches for similar payloads. The benefit of this approach however is to enable existing clients and APIs to support it gradually and gracefully. i.e. For an existing API doing JSON today, you can drop in CBOR support on both sides, not change anything else in your applicative code, and rip the performance benefits. Which is much less work than having to entirely rebuild both the API and the client for GraphQL/GRPc. (but then of course performance is not the only consideration)

I hope this lengthy reply answers more of your questions, don't hesitate to follow up.

[ewinnington]

Oh great Overlord ;), thank you so much for that in depth and thoughtful answer.

Thank you also for the pointer to CBOR, I was not aware of it. Might be one to investigate for some of my internal use cases.

For RAML, I’m sure a conversion of api spec to OpenApi is quick, possible and probably good enough. Mulesoft Anypoint provides that conversion functionality in the box - might even be available as a library.

AsyncApi on the other hand really targets a much wider spectrum and would probably involve support for more protocols - requiring a deeper investment to support.

I’m very happy to hear that you have internally thought about it. It’s true that the market is dominated by openapi specs and thus you can provide the most value for effort by targeting it.

Just the websockets definition is missing from the official spec of OpenAPI and not currently in scope for official support last I read. One vendor’s API I consume has simply used the HTTP OPTIONS verb to document the websockets messages since the verb is so seldom used.