microsoft
[Kiota.Builder] Provide option/configuration to generate project/dependency file definitions for generic ApiClient
Languages like PHP, TypeScript, and Java can use different "native http clients" by default. We should consider making this configurable so that we generate the dependency definitions for the default ApiClient to use our assumptions for the native http client for the default generic ApiClient so that it "just works". Otherwise, it would be the responsibility of the customer to discern and specify which native httpclient should be used with the generic ApiClient.
In the case of PHP, we would generate a composer.json with an entry that defines the dependency on PHP Kiota Core. This way the generated client is complete with the dependencies it needs. We could extend this further to allow any arbitrary dependency to be defined at generation time.
This should be configurable so we can define the dependency on Graph Core at generation time. AB#11167
Hey @michaelMainer Thanks for posting this. Early on @darrelmiller and I made the decision that Kiota should not touch the project files/interact with the dependency manager. There are multiple reasons for that:
- Touching project files directly would be a very fast way to corrupt projects, not only because some ecosystem rely on lock files but also because a build after that doesn't necessarily restore on the next run.
- There's a multitude of formats out there that can evolve over time
- The dependencies file is not necessarily at the same level as the project files (look at java core) or as the output path (java with the namespace matching.
- There's a multitude of package managers as well (java: gradle/maven, js: npm/pnpm/yarn..., donet: nuget, core cli,...)
This would add a significant burden on Kiota and probably lead to a poor experience in a lot of cases. There's also the other case where people leverage other libraries than the default ones, they'd have to uninstall the dependencies we installed after each generation (or we'd have to provide some kind of bypass). Those libraries could be on private feeds (requiring some kind of auth)...
For all those reasons I think we should stay away from that unless we see a strong demand for it.
Scaffolding a project to host a Kiota SDK is definitely tooling that could be built. However, to date, Kiota has avoided doing that. Kiota is potentially going to be run on every build of a project. Also Kiota could be run multiple times for different APIs in the same project. It could also, in theory, use different HTTP cores for each target API. Because of the way it is used, we should probably avoid building project scaffolding into Kiota. We should use whatever is the native project scaffolding tooling for the platform. Let's not re-invent that wheel.
We should use whatever is the native project scaffolding tooling for the platform. Let's not re-invent that wheel. Kiota should not touch the project files/interact with the dependency manager.
In general, I agree with you here. I don't think that this will the best Kiota.Builder first run experience. I was more thinking about the Kiota.Builder first run scenario and having a simple path to success. If we don't provide a basic project file for that successful first run of Kiota.Builder, I expect a workflow something like:
- Documentation that instructs the client developer to install scaffolding tool if not already installed. We will need to provide instructions on which configuration to use. Instruct the customer to run the command to install all dependencies.
- Instruct the client developer to install the Kiota.Core dependency.
- Instruct the client developer to install the auth dependency.
I think this experience may be error prone for a first-run experience. If we had a simple project file generated, the successful first run experience would be:
- Run
install.
Perhaps I'm oversimplifying an experience here.
Now then, after a successful first run, when the client developer understand Kiota, they likely will not want or need the basic project structure we provided at first-run. I expect for the most part, like @darrelmiller mentioned , Kiota.Builder will be run regularly. The client developer will move the code files into their own project. They do not need a project file from Kiota.Builder at this time, they will have one already.
<lookingOutTheWindow>I wonder what the first-run experience is like for other OpenAPI generators.</lookingOutTheWindow>
Since that discussion, we've made lots of improvements to the getting started documentation. And more improvements are coming in the Microsoft Graph public docs for the self serve clients scenario. https://microsoft.github.io/kiota/get-started/ Closing for now.