Alternative implementations

[andreaTP]

I started working on a basic dependency-free HTTP client (using the client shipped with JDK 11+) for Kiota here:
https://github.com/andreaTP/kiota-utils/blob/main/http/jdk-http/src/main/java/io/apicurio/kiota/http/JdkHttpRequestAdapter.java

I would like to know if you would consider those additions in this repository or if you prefer to have them as third-party implementations.

I was planning on eventually working on:

• a vert-x based Http client
• Jackson based serializers

[baywet]

Hi @andreaTP ,
Thank you for working on alternative implementations.
The main reason why we designed abstractions to be independent of any implementation detail is for that specific scenario.
We want people to be able to come up with their own implementations if they prefer other libraries without "depending on us". We anticipate that a majority of people will just use the default implementations we provide.

While we won't take additional implementations on this main repository, this is to reduce maintenance burden on our team, we'd be more than happy to have a list of alternative implementations either here or on the main kiota repository.

And of course, if you see anything wrong with our default implementation, we're more than happy to get issues and pull requests, but you already know that.

What do you think?

[andreaTP]

we'd be more than happy to have a list of alternative implementations either here or on the main kiota repository.

Nice!

What do you think?

I completely understand and acknowledge your position here 🙂 and I'm up to publish and maintain alternative implementations of the libraries.

Unfortunately, this approach is going to require some additional effort for managing the compatibility matrix (at least on my side):

• Kiota CLI version
• Kiota CLI "abstractions" version (from the info command)
• List (e.g. serialization-form have been recently added) and versions of the concrete compatible implementations

How do you see this process working if we decide to fully commit to Kiota?

• fully reactive: after a Kiota and Kiota-java release I would need to iterate and publish everything accordingly
• release train: I get a notification of an upcoming Kiota release and I have a time-window to update the alternative implementations, align everything up and iterate if we discover bugs
• cooperative: we can cooperate in getting releases done and we even contribute back to the main Kiota repository with the alternative libraries versions ( e.g. adding additional or alternative entries here )

Or anything in between 🙂

[baywet]

I'd start to say that this is the "first time" for kiota that an implementer of alternatives reaches out. So we're more than willing to iterate until we find a recipe that works for everyone.
We should also acknowledge that a significant portion of implementers might not reach out/we might not be aware of the alternatives, and should design a communication process that accounts for that.

Kiota generation & kiota abstractions

One guarantee from the support policy is that once kiota itself and a given language experience reaches GA, any change that'd mandate a binary breaking change (change in the shape of the fluent API being generated, changes in the interfaces of abstractions, etc...) would mandate a major bump to kiota itself, and the supporting libraries for the given language. While breaking changes might still happen until Kiota + the Java experience reach GA, we're doing our best to get the final ones in as we speak, and to get to GA shortly after.

We've also mentioned that as a language moves to a new major version, we wouldn't be providing support for the older version anymore. So the consumers choice becomes: stick with the older version and accumulate technical debt or pay an upgrade cost. We think that's going to help make the ecosystem successful by reducing the number of versions 3rd parties need to support.

These aspects should reduce your supportability matrix.

And as for the anticipated remaining breaking changes, I think these are the only ones that'd impact implementers in java:

• Java Period and Duration needs an aggregation type kiota#2069
• multipart/form-data request content type is not handled properly kiota#220

Additional implementations

We're not expecting you to have to cover the full list of implementations we cover as a 3rd party implementer. It's perfectly fine to say "I'm going to provide an alternative to gson with jackson for json serialization but rely on the Microsoft provided implementation for the form serialization". In facts, we'd rather have you contribute to the "trivial" implementations that do not rely on additional libraries rather than reimplement them.

Listing alternatives

This list in the appsettings is a placeholder/default value. We also documented an OpenAPI extension. The idea being the following : API owners are able to "push" different implementations on client applications by adding this extension to their OpenAPI description. The info command will use that as a data source if the -d argument is provided. I'm really curious to know whether that covers your scenarios?

Collaboration model

This is where I think we need to experiment. We're always happy to see contributions (generator, libs, etc...) and we'll do our best to get them merged as they represent a net benefit for everyone. (well I don't need to sell OSS to Red Hat)
I think we need to acknowledge we won't know about some implementations (public or private) and those will always be reactive.
Knowing how Microsoft operates in terms of planning, I think we also need to acknowledge that "delaying a release because of third parties" will be a very hard sell internally. And if we turn it the other way around "putting pressure on an OSS maintainer to align so we can release" is probably going to burn out those known maintainers who might be doing this on their own time (outside of work hours) etc...
This is why the async collaborative model feels like the one that has the best chances of succeeding at this point. Where anybody with a contribution big or small can open an issue to talk about it, identify which release it'd be able to be inserted into etc. What do you think?

Thanks for powering through that lengthy answer, I hope that clarifies a lot of things. Don't hesitate to provide feedback/ask additional questions.

[andreaTP]

We also documented an OpenAPI extension

This is really awesome, for sure a step in the right direction. Thanks for mentioning it!
I'm not 100% sure how this can be leveraged in an automated way but I will eventually try to experiment a bit.

"delaying a release because of third parties" will be a very hard sell internally

The selling point here is the guarantee that the (OSS) ecosystem is moving at the same speed as the main project (hence fostering it).
The big technical advantage for the core maintainers is that by running the ecosystem CI on other projects using the pre-release build you are very likely to spot bugs before a release happens and, eventually, intrinsically increment the test coverage and stability of the entire project.
Please, note that I'm not asking you to buy into this model, and I completely understand the downsides of it.
I'm only mentioning it for context as we have a pretty successful experience at RH with Quarkiverse which is again about "community extensions".

Thanks a ton for taking the time to dump this detailed answer, highly appreciated 🙏

[baywet]

Thanks for the follow up, here is what I suggest at this point:

• Explore the extension, tell us whether it covers your scenarios or if there are gaps we can address.
• Let's experiment with the async collaboration for now, and revisit that if we see signs of friction for the community.
• Let's at least document the alternatives on Kiota's doc pages for now, don't hesitate to send out a PR once you have a "ready" implementation.

Does that plan work for you?

[andreaTP]

Sounds like a plan 👍 thanks for bearing with me!

[baywet]

Perfect. Closing for now as there are no follow-ups specific to this repo. Let me know if we need to re-open at any point.