Builder should support application-specific JSON MIME specifiers

[hermann-noll]

It seems like currently only application/json is supported as MIME specifier. Instead the builder should also accept specifiers with the pattern application/myapp+json as is the case for e.g. GitHub (application/vnd.github.mercy-preview+json)

Additionally when using an OpenAPI document like below the kiota builder throws a NullReferenceException instead of a diagnostic error.

swagger: '2.0'
info:
  version: 1.0.0
  title: Sample
  description: ''
host: hostname
schemes:
  - https
paths:
  /something:
    get:
      description: ''
      produces:
        - application/myapp+json
      responses:
        '400':
          description: Indicates failure.
          schema:
            type: string

[baywet]

Hi @hermann-noll
Thanks for trying kiota and thanks for reporting this issue.

There are multiple aspects to this issue, here is the detailed explanation:

While the generator aims to support multiple content types for the payload (request/response), it's currently hard-coded to only look for the application/json and application/octect-stream content types.

kiota/src/Kiota.Builder/Extensions/OpenApiOperationExtensions.cs

Line 14 in 6e6f379

.Where(c => c.Key == "application/json")

kiota/src/Kiota.Builder/KiotaBuilder.cs

Line 550 in 6e6f379

private const string RequestBodyBinaryContentType = "application/octet-stream";

This aspect dates from the POC era of Kiota and we have multiple issues logged to unlock additional content types/scenarios

• application/x-www-form-urlencoded request content type is not handled properly #219
• multipart/form-data request content type is not handled properly #220
• file type should be mapped as a binary type #221
• An operation without a return schema should default to a Stream/byte[] response type. #546
• Support for raw content in text/plain responses #878

Once the generation goes through, for the client to work properly, it needs registered ParseNode factories and SerializationWriter factories to handle the payloads correctly. They are also locked to a very specific content type

kiota/serialization/dotnet/json/src/JsonParseNodeFactory.cs

Line 20 in 6e6f379

public string ValidContentType { get; } = "application/json";

kiota/serialization/dotnet/json/src/JsonSerializationWriterFactory.cs

Line 18 in 6e6f379

public string ValidContentType { get; } = "application/json";

In theory, the reason why the API returns to your request a vendor specific mime type is because your application should be a different parser than "just JSON" to parse the response. It is not always the case in practice and parsing with the default implementations we provide might work just fine.
In any case, I believe that as the very least a new set of libraries should be introduced for that vendor type so even if they only inherit from the default to override the mime type, they can evolve separately should the need arise in the future.

Does all of that make sense?

In which case here is what I suggest should be done:

• update the code in the kiota generator to use a regex instead of hard-coded constant, during the generation process
• standup a new repo for those vendor specific JSON libs

[darrelmiller]

@baywet We can safely assume that any media type that ends in +json can be parsed with our standard JSON parsing. https://datatracker.ietf.org/doc/html/rfc6838#section-4.2.8

We should figure out what the model is for adding support for standard JSON based media types like application/problem+json and application/collection+json.

[baywet]

thanks for jumping in @darrelmiller. So effectively parsing a application/vnd+json response with our current implementations should also work because the body "is just JSON"?

[baywet]

Hi @hermann-noll ,
Thanks for your patience on this one.
I've just authored #1461 that addresses this. I yet have to author PRs for dotnet and typescript as we moved those libraries to other repos.

generation change

Imagining we get the following content type in the description for the response content application/vnd.github.mercy-preview+json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8.

1. ;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8 will be ignored (considered as application/vnd.github.mercy-preview+json
2. vnd.github.mercy-preview+ will be ignored (considered application/json
3. The described types will get generated

runtime changes

Imagining we get the following content type (runtime application/vnd.github.mercy-preview+json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8

1. ;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8 will be ignored (considered as application/vnd.github.mercy-preview+json
2. The registry will look for a serialization writer/parse node factory for application/vnd.github.mercy-preview+json, use that if it finds it.
3. If it doesn't find it, it'll look for application/json instead.

[hermann-noll]

Hello @baywet ,

Great to hear, I am looking forward to using these changes 👍