Good-bye Boilerplate, Hello Kiota-for-AL – Prototype, Repos & How you can help

by

TL;DR
We now have a working Kiota language generator for AL, a “companion app”, and a first sample project. Everything is OSS – and I need your feedback to make the current prototype production-ready.

From conference stage to GitHub

At ColorCloud Hamburg Tobias and I showed how Kiota – Microsoft’s cross-language OpenAPI client generator – can help us reduce the work of creating boilerplate code that haunts not only Business Central integrations, but most REST API integrations.
The hallway question: “When can I try this?”
Answer: right now. 🎉

1 | SimonOfHH/kiota (kiota-al branch)

  • What – a fork of the official Kiota repo featuring a brand-new AL generator.
  • Key folders
    • /Refiners/ – modify generated DOM to be suitable for AL
    • /Writers/al/ – object-mapping to writers
  • Status – first draft basically.
  • Quick start: see sample repo

Heads-up for reviewers – the “documentation hack”

My main goal was to touch as little of Kiota’s core code as possible so that the AL work can merge upstream with minimal friction.
To avoid sprinkling new properties and interfaces through the DOM, I used a small workaround:

  • most Kiota DOM elements already carry a Documentation object that has plain string properties.
  • I piggy-back extra metadata onto one of those strings, appending a semicolon-separated list of key-value pairs after ||, e.g.: “Original summary text ||source=property;type=list“
  • CustomPropertyExtension.cs (in /writers/al) parses and later strips these tags, so nothing leaks into the generated AL files.

If you stumble over oddly formatted documentation strings in the branch, that’s why. I’m open to cleaner ideas, but this kept the diff small and the merge path simple.

2 | Draft PR #6495 in the upstream repo

https://github.com/microsoft/kiota/pull/6495

  • Purpose – keep all design discussion in the main repo from day 1.
  • Status – draft until we get wider feedback from the AL community
  • Where to jump in – feel free to either review the Kiota-code directly or check out the resulting client in the sample repo.

3 | Kiota.Abstractions-al

https://github.com/SimonOfHH/Kiota.Abstractions-al

A foundational Business Central extension that every Kiota-generated AL client depends on.
It plays a similar role that Microsoft.Kiota.Bundle plays in .NET, but it’s shaped for the AL world.

Key building blocks

  • Base interfaces – IApiClient, IModelClass and friends provide a common contract for all generated code.
  • Utilities
    • JSON Helper SOHH – lightweight helpers around BC’s native JsonObject.
    • StreamHelper SOHH – convenience wrappers for stream operations.
  • Configuration – Kiota ClientConfig codeunit stores configurations like base URL and auth data.
  • Request handling – Kiota RequestHandler codeunit orchestrates HTTP requests & responses, exposing a clean AL API.

Note: this is an early draft; the structure and naming may evolve as the AL generator stabilises. Contributions and feedback are very welcome!

4 | kiota-al-samples

https://github.com/SimonOfHH/kiota-al-samples

A playground repo that shows what the AL generator produces and how to run it in Business Central.
Right now it contains one fully-worked example; more will land soon.

What’s inside

  • petstore-sample/ – an AL client generated from the public PetStore OpenAPI spec.
    • Demonstrates the basic request-builder pattern, strongly typed models and simple paging.
  • …more to come… – will hopefully grow, based on community feedback and discussions

Call to Action – let’s make the prototype production-ready!

  1. Clone & generate a client for your OpenAPI – shout if the generator chokes and try out the handling of your generated clients in code.
  2. Review the PR – even a 👍 emoji helps and Kiota maintainers might gauge interest.
  3. Open issues or PRs in any repo – if you want to fix typos or ask what the heck I thought with the current design – please reach out or contribute directly.
  4. Discuss naming – I chose Codeunit <Thing>RequestBuilder. Too verbose? Too dotnet-y? Better ideas?
  5. Star & Watch the repos so you don’t miss the furious commit storm over the next weeks and months.
  6. Spread the word – let’s use it and improve it 😊

Goal: merge into upstream Kiota. Let’s do us all a favor and get this stuff production-ready. Might still be a lot of work, but I can’t wait to not write these clients manually anymore

Grab a coffee, open VS Code, git clone, and make some noise.
Let’s kill manual boilerplate together!

— Simon

Leave a Comment