Celebrations

Back in January, I celebrated 5 years at Microsoft! It’s incredible how fast time can fly. I initially started working as a program manager II on Microsoft Graph Change Notifications (aka webhooks) and Change Tracking (aka delta queries). A transfer and a few promotions later I’m now a Principal Software Developer, working on Microsoft Graph client experiences (SDKs, kiota, copilot extensibility, OpenAPI…)

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. Often mapped to exclusive unions. (| sign in TypeScript)

This breaks down for many reasons. Let’s see why.

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. This is why in Kiota we’ve made the opiniated choice of making all scalar types nullable when generating models, regardless of what’s in the API description.

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. While it works, the generator should not have the responsibility to arbitrarily define naming conventions. There should instead be a placeholder for the API owner to dictate those conventions.

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. The second example is an impossible combination that’s allowed because the JSON schema specification does not mandate any validation of the format property. If we dive deeper into this aspect, we find that a lot of type combinations are considered valid by conventions, but there’s no central registry to date, although OpenAPI is working on one: