Coding Stephan

Kiota serializing

Using Kiota to serialize your data sounds like a great idea for my new project. But why should I care about Kiota serializing? Let’s find out!

What is Kiota?

Kiota is a tool that helps you build HTTP clients for your APIs. It’s a great tool for developers who want to build APIs that are easy to use and maintain. It provided clients for multiple languages, including C#, Java, and TypeScript. And they all feel the same, so you can easily support multiple developers working with different languages.

This tool is fully open-source and backed by Microsoft. They use it themselves to generate clients for their APIs. The Graph SDK is a great example of this. It has a client for java, c#, php and powershell. And they all feel the same. In the beginning of this year, GitHub announced that they are switching to Kiota to generate their api clients.

Let’s talk about serializing

Serializing is the process of converting an object into a format that can be easily stored or transmitted. If you update a user in Entra using the Graph SDK, you have this user object. If you want to send this update to the server, Kiota serializes this object into a JSON string. And that is then send to the specific endpoint.

I’m talking serializing to json here. Apart from being a great format for APIs, it’s also a great format for storing data. A human can “easily” read it, and you can convert it back to an object. This is called deserializing. Kiota also supports this, so you can easily convert the response from the server back to an object.

Great, it already works out of the box. But why should you care about it?

WinTuner story

I’m currently working on a PowerShell module called WinTuner, which will help administrators to package any app from WinGet into a package for Intune. It also has a way to upload the app to Intune, which is done using the Graph SDK (which is generated by Kiota).

When generating the package, that later will be uploaded to Intune, I created a file that has all the details that are needed to upload the app. It’s a JSON file, but it’s not directly deserializable to the object that the Graph SDK expects. Wouldn’t it be great if I could just leverage the already built-in serialization of Kiota?

Serializing with Kiota

The use-case is that I don’t want to built my own object, (de)serialize it, convert it to the right object and then send it to the server. I just want to use the object that the Graph SDK expects, this would make integration with other applications a lot easier. So there you have it, I want to move my code to use Kiota for serializing.

Backing store

The Kiota dotnet package uses a backing store, which is a dictionary that allows the SDK to only serialize the properties that are changed after the object was created (and marked as loaded).

  1. Load a user from the server
  2. The object is marked as loaded automatically
  3. Change two properties
  4. Send a patch user request to the server
  5. Only the two properties are serialized, and the rest is not.

The resulting message is a lot smaller then if all the properties were serialized. This is great for performance, but not for my use-case. I want to serialize the whole object, not just the changes.

Skipping the backing store

In the design of the Kiota libraries, they just went for speed. The backing store is a great way to only send the changes, but there was no way to disable this. So I’m off to the source code to see if there might be a way to disable this. And I can tell you, there wasn’t. I had the source code already open, so I though how users would be able to disable this, and eventually created this pull request. Having a holiday in between made it take a bit longer then I wanted, but it’s now merged and will be available in the next release.

Code example

So how does this look in code? I have a User object that I want to serialize. I can just use the JsonSerializer that is built-in in the Kiota library.

using Microsoft.Kiota.Abstractions.Serialization;

var graphClient = new GraphServiceClient(...); // This is the client that is generated by Kiota
var user = await graphClient.Users["id"].GetAsync(); // Load the user from the Graph API

// Serialize the user to a JSON string (using the backing store)
var jsonOnlyChanged = await KiotaSerializer.SerializeAsString("application/json", user, true, CancellationToken.None);

// Serialize the user to a JSON string
var json = await KiotaSerializer.SerializeAsString("application/json", user, false, CancellationToken.None);

Future improvements

I’m a big fan of Extension methods and in a future version I hope they implement the code above as extension methods, like I suggested in this issue.

That would change the code above to:

using Microsoft.Kiota.Serialization.Json;
...

// This is the client that is generated by Kiota
var graphClient = new GraphServiceClient(...);
// Load the user from the Graph API
var user = await graphClient.Users["id"].GetAsync(); 

var json = await user.SerializeAsJsonString(false, CancellationToken.None);

Deserializing

We will not only be storing the objects as json, we also want them back from storage.

using Microsoft.Kiota.Abstractions.Serialization;

var json = "{ \"id\": \"1234\", \"displayName\": \"John Doe\" }"; // load from storage 😉
// TA-DA! We have a user object again
var user = KiotaJsonSerializer.Deserialize<User>(json);

Conclusion

With this latest change in the Kiota library, developers who are already using a Kiota generated client in their applications can now also use it to serialize their objects. This makes it easier to integrate with other applications and services. And it’s a great way to store your objects in a human-readable format.

WinTuner future?

Apart from the use case described above, I’m also thinking about exporting/importing conditional access policies. By downloading them from one tenant, saving them (using Kiota) to a folder and then uploading them to another tenant. This would make it a lot easier to migrate conditional access policies between tenants. Templates anyone? There are several other Microsoft MVPs that spend a lot of time on creating a set of the best practices for conditional access policies. Being able to upload those to your tenant would be the next best thing for WinTuner.