Weakly typed path parameters and nullable response properties (C#)

[kimbirkelund]

I'm trying to use Kiota to generate a client for an internal API, but I'm running into a few issues that I can't seem to find documentation for - either in the actual documentation or previous issues, but I apologize if I'm just not looking hard enough :)

I'm using the following spec snippet for the issues below but it happens in samples as well:

"/foo/{fooId}": {
  "get": {
    "parameters": [
      {
        "name": "fooId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "integer",
          "format": "int32"
        }
      }
    ],
    "responses": {
      "200": {
        "description": "OK",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/FooResponse"
            }}}}}}}

"FooResponse": {
  "required": [
    "fooId"
  ],
  "type": "object",
  "properties": {
    "fooId": {
      "type": "integer",
      "format": "int32"
    }
  },
  "additionalProperties": false
}

In the generated client I see the following issues:

1. In the request builder the indexer parameter is string position although the spec clearly states that it is an integer named fooId.

2. The generated WithFooItemRequestBuilder.GetAsync returns Task<FooResponse?> even though spec says it always returns a response. I could understand if this was to map 404 to null, but this does not appear to be the case.

3. In the FooResponse model the property for fooId, which in the spec is a required integer, is also nullable and this appears to be the case for all properties.

From what I've read Kiota is intended to generate easily usable clients from the consumer point of view so consistency is more important than tailoring the client to something the producer would like.

I'm fully on board with this perspective, but these issues, to me, does not align with that. So I'm curious as to why these choices were made.

[baywet]

Hi @kimbirkelund
Thanks for your interest in Kiota and for reaching out.

gaps in documentation

This is something we're aware of and we're working to address it. In the meantime we encourage people reaching out to outline specific gaps and get their questions answered.

indexer argument type

Arguably this could be classified as a bug/feature gap. If you had multiple path parameters in the same path segment you'd instead get a method with multiple parameters. And those parameters would be properly typed. This is somewhat related to #2318. Reasons for that are somewhat historical, indexers were added at the beginning of kiota's journey, we haven't revisited them much since then, and the API we were using to test things (Microsoft Graph) probably only ever has string path parameters for indexers.

I think we could make that change safely, although it might be a breaking change to some people, the impact would be limited. As for the name, I'm not sure the name of the indexer parameter really matters? But I'd be happy to read your thoughts on that topic. Would you be willing to submit a pull request for the indexer type?

nullable return types

Our experience with descriptions out there is they are often lacking enough information around that. Not only people would need to be explicit about 200 response and its nullability, but they'd have to make sure the API respects that. Also, maybe for post/put/patch... and not for get, you have to account for 204's that are often left undescribed and other cases like that which are fairly common. To provide consistency and reliability for inaccurate descriptions we made that opiniated decision.

nullable properties on models

The reason why kiota is opiniated this way is because most descriptions don't consider the client experience with nullability and selection. In lots of cases even though "property foo is required", the client can still provide a selection that doesn't include that property, and the payload won't contain it, which means it might be null at runtime. Also required is not specific enough, is it required in the context of getting the resource? in the context of creating it or updating it? etc... There is design work going on at the standards level to address that gap. Once it's addressed there, we can imagine improving the experience in kiota.

I hope that lengthy post answers your questions, don't hesitate to follow up with additional questions or remarks.

[darrelmiller]

Fixing this would be good but it is a breaking change so I have moved it into our v2 milestone.

[kimbirkelund]

I haven't the time right now to make a proper answer. I just Ed wanted to say that I'd be happy to try to fix the indexer issue.

I was actually starting to look at it but couldn't find where the code for the language specific generators were located.

If you could point me in the right direction I'll try and put a PR together.

Also thanks for a cool tool and a quick reply :-)