For years Microsoft Graph has been serving billions of requests a day as one of the main REST APIs of Microsoft services. The service has become key infrastructure for Microsoft’s own applications, line of business solutions and third-party commercial solutions. Any critical piece of infrastructure comes along with rigorous responsibilities: maintain, support, and secure. And sometimes this infrastructure needs to be “upgraded” to the latest standards which improve the value provided to its users through better safety, better interoperability, and better performance.

Introduction Over the past few months I found myself struggling to get a working installation of the dotnet SDK on Ubuntu running off Windows Subsystems for Linux (WSL). This is partly due to the fact new installation methods have been added over the years, others have been deprecated, and it’s really easy to inadvertently update from one installation method to another, messing up everything by the same occasion. The documentation overview on the topic currently suggests the following methods:

Introduction We recently announced the general availability of Kiota, an open source client generator for REST APIs with an OpenAPI description. I am the co-founder of this product, and this launch matches my 3 years anniversary at Microsoft, so I thought I would take the time to write about my experience of taking a product from idea to v1 at Microsoft. Throughout my career, I have been involved with multiple “products”: a second-hand marketplace for industrial hardware, an enterprise social network solution, a localization and translation solution for SharePoint, and an IoT based temperature management optimization solution.

This is the final entry in our series. First, I’d like to thank the Microsoft Graph DevX team for all the hard work to make Kiota a reality over the last 2 years. Special thanks to Darrel Miller for mentoring me on JSON schema and OpenAPI as well as the deep and open technical discussions. Then, I’d like to thank the organizing committee for the API specifications conference for inviting me to speak about this topic, which sparked a bunch of interesting follow ups during the event.

Seventh pattern of our series: composed types. JSON schema defines 3 main ways of composing types: allOf: the data must validate all the schemas described in the collection. This is often mapped to inheritance in Object Oriented Programming (OOP) although it wasn’t designed for that purpose. anyOf: the data must validate one or more of the schemas. Often mapped to inclusive unions/intersections. (& sign in TypeScript) oneOf: the data must validate a single schema in the collection.

Sixth pattern of our series, nullable types. This one will be harder to crack. I’ve concluded that marking scalar types as nullable for the purpose of API client generation is not a useful piece of information. While the property might not be nullable on the service itself, it might not be selected by the client, or filtered out for security reasons, and the client needs to convey that information to the application.

Fifth pattern of our series: paging conventions. The following examples describes a page as with a value property (array) which will contain the resulting items, and a nextLink property which contains the link to the next page. paths: /path: get: summary: Get description: Get operationId: get tags: - api1 responses: '200': description: OK content: application/json: schema: type: object properties: value: type: array items: type: string nextLink: type: string nullable: true x-ms-pageable: nextLinkName: nextLink itemName: value operationName: get This is missing a lot of information to make the life of the client easier:

Fourth pattern of our series: naming conventions for unnamed things. When Kiota generates models for requests bodies and responses, two cases are possible: either the type is defined in a reusable component schema, which means the component is named and Kiota can use that name for the generated model. Or the type is defined inline, in which case Kiota needs to rely on naming conventions. paths: /path: get: summary: Get description: Get operationId: get tags: - api1 responses: '200': description: OK content: application/json: schema: type: object # PathResponse properties: inlineProperty: type: object # PathResponseInlinePropertyModel properties: subInlineProp: type: object # PathResponseInlinePropertyModelSubInlinePropModel properties: subSubInlineProp: type: string inlineArrayProperty: type: array items: type: object # PathResponseInlineArrayPropertyModel properties: subInlineProp: type: string In the snippet above the generated types will be named according to the path segment name and according to naming suffixes always appended to the parent type name.

Third pattern of our series looking at how we could improve the OpenAPI specification for the purpose of code generation. Today we’ll look at type and formats which are crucial to generate accurate and useful clients. components: schemas: Model: type: object properties: noType: properties: subProp: type: string impossibleCombination: type: string format: int32 In the snippet above, for the first example properties are defined, which hints the type should be an object, but the type property is not set to object.

Second pattern of our series: collections. components: schemas: Model: type: object properties: stringArray: type: array items: type: string stringArrayNoType: items: type: string arrayOfUnknown: type: array items: {} In the above snippet, stringArray describes an array of string values. While this works well for the purpose of generating code, it is not very specific. It is assumed that an array will be enough for the application developer, and while that might be the case, signaling generator whether to use a basic array or a more advanced data structure would help for scenarios where the client application cannot have duplicate entries, or needs to quickly find one of the entries, or needs to do some sorting, etc.