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:

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.

First pattern of our series: enumerations. They are essential to any programing language to describe a discrete set of options. Consider the following examples:

components:
  schemas:
    Model:
      type: object
      properties:
        enumString:
          type: string
          enum:
          - value1
          - value2
        enumInteger:
          type: integer
          enum:
          - 1
          - 2
        enumBoolean:
          type: boolean
          enum:
          - true
          - false

EnumString describes two possible values, however it’s missing a lot of information:

• We can’t specify a different serialization value from the symbol.
• We can’t specify a description which would be helpful to developers who discover the API surface through a client.

EnumInteger describes an integer type enumeration, where each option is a number. While this is a valid scenario, it makes code generation harder as most programming languages don’t accept numbers or strings starting with numbers as valid symbols which leads to compilation errors. Additionally, if the enumeration values are powers of 2, the enumeration is flaggable (supports compounded values through a bitwise or). But we have no way to convey this information.

Over the last two years I’ve been working on a modern client generator for OpenAPI described APIs: project kiota. Kiota generates models and chained methods to allow developers to build requests for any REST API. The generated clients handle serialization, deserialization, authentication, retrying transient errors, following (or not) redirections and much more. Using a generated client saves developers from having to re-implement those aspects and enables them to focus on the core logic of the application.

I’m honoured to announce that I’ve been selected to speak at the Caribbean Developer Conference 2022 happening in Punta Cana Nov 3-5th. This is the first time I’ll be speaking at this event, but I’ve heard lots of good things about it from people who previously spoke there.

I’ll be presenting “Turbocharge your API integration with Microsoft Kiota” where I’ll be introducing through lots of demonstrations how you can generate a client generated for any OpenAPI described API using Microsoft Kiota and other tools.

I’m honoured to announce that I’ve been selected to speak at the CollabDays Belgium 2022 (formerly SPS Events, aka SharePoint Saturday) happening in Brussels Saturday 15th of October. This event is dear to my heart as it’s one of the first international events I ever got to speak at, it always attracts a great crowd and brings together internationally regarded speakers.

I’ll be presenting “Turbocharge your API integration with Microsoft Kiota” where I’ll be introducing through lots of demonstrations how you can generate a client generated for any OpenAPI described API using Microsoft Kiota and other tools.

I’m extremely pleased to announce I’ll be speaking at the API specification conference 2022 in San Francisco, Sept 19-21st. During “Lessons learned from client generation, gaps and suggestions to address them”, we’ll be reviewing my 2 years experience building an OpenAPI based client generator and trying to identify solutions to ease up code generation, leading to better clients.

The API specification conference is the first in person event I’ll be presenting at in almost 3 years, I’m really excited and a bit nervous (do I even remember how to do this anymore?). This conference focuses on the standards (HTTP, OpenAPI, JSON Schema…) and practices revolving around building APIs, it is organized in partnership with the Linux Foundation and the lineup is impressive!

One year as a Software Developer at Microsoft

Introduction

Back in September 2020, I published a blog post about my experience as a Program Manager at Microsoft that was well received. It made me realize that the community was curious and interested about this role. In this post, I will share my insights as a developer.

Before we begin, keep in mind this is my personal experience, which may differ a lot from team to team, product to product and depend on other circumstances (being remote, culture, etc…).

Introduction

Back in August 2020 I became the main maintainer of the Microsoft Graph Java SDK.

The team had to deprioritize this SDK in favor of other languages due to a lack of staff. About 100+ issues were open, as well as 15 pull requests from the community. Dependencies and tooling had not been updated, the Android story was unclear, no innovation had been done in a long time, the repository felt abandoned and caused a lot of frustrations…