Feature Request: option to generate method per content type

[MiyaGrace (JeroMiya)]

I've split this discussion off from a bug report here:
#6451

The bug report is still valid, but I'd like to request a new feature related to the bug. I have an external API with an OpenAPI spec I'm attempting to create a Kiota client for in C#. While I would not design my own APIs like this, this API has a POST endpoint that supports multiple content types, and the behavior of the endpoint is different depending on the content type submitted. Here is an example OpenApi spec that demonstrates the situation:

openapi: 3.0.3
info:
  title: User-API
  description: External api for users
  version: "1.0"
servers:
- url: https://example.com/api
paths:
  /users:
    post:
      tags:
      - create
      operationId: create-user
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
              - picture
              - info
              type: object
              properties:
                info:
                  $ref: "#/components/schemas/create-user-info-request"
                picture:
                  type: string
                  format: binary
          application/json:
            schema:
              $ref: "#/components/schemas/create-user-info-request"
      responses:
        "201":
          description: Created
        "400":
          description: Bad Request
components:
  schemas:
    create-user-info-request:
      title: create-user-info-request
      required:
      - firstName
      - lastName
      type: object
      properties:
        firstName:
          type: string
        lastName:
          type: string
        templateId:
          type: string
      x-internal: false

Note the templateId field in the create-user-info-request model. Imagine that this endpoint supports templates for the user profile picture when a photo isn't available - maybe with a logo or icons based on the role of the user. Anyway, the POST /users endpoint in this example behaves differently depending on if you use multipart/form-data as the content type or the application/json type. In both cases, you submit a create-user-info-request object as part of the request. However, if you submit with content type application/json, and you provide a valid templateId in the body of the request, the second content type creates a profile picture based on the template. However, if you use the multipart/form-data content type, and include a picture in the picture part of the request, the endpoint will use the submitted picture as the profile picture.

Unfortunately, Kiota can't currently support this kind of API. Although currently bugged (see: #6451), even if Kiota worked as designed, we would not be able to use the multipart/form-data content type, which in our case is the one we use for our own workflow. As I said, this wouldn't have been my design choice, but it's an external API we have no control over. We need to be able to use both content types to support all the workflows of this endpoint.

Therefor, I propose a new generator option, for now I'll name it --method-per-content-type, which should be off by default to avoid breaking changes. When enabled, this option will change the way the generator handles multiple content types in a given request. Instead of choosing the most "structured" content type (in the above example, that would be application/json), the generator would instead generate a method for each content type. So as to support languages that don't have support for type based method overloads, and to avoid collisions in method signature for content types that would generate the same signature, the methods should include the content type in the name of the method, translated to an identifier using the conventions of the target language.

For example, in the above sample OpenApi spec, when the --method-per-content-type is enabled, instead of a single PostAsync method being generated (again, note this is bugged currently - see linked issue above), there would be two methods: PostApplicationJsonAsync and PostMultipartFormDataAsync. In this case, the signatures would be different with PostMultipartFormDataAsync taking a MultipartBody as an argument, and PostApplicationJsonAsync taking a CreateUserInfoRequest (in the C# generated output, at least).

So that, when enabled, the proposed new --method-per-content-type option would allow us to use Kiota to generate a client that enables us to explicitly choose which content type to use when an endpoint in the source spec supports multiple content types and which differs in behavior depending on which content type is submitted.

[Vincent Biret (baywet)]

Hi MiyaGrace (@JeroMiya)
Thank you for using kiota and for reaching out.

This is something we discussed a while ago in #2317

Effectively, there'd be a need to vary per request media type, response media type AND status code to fully implement that.

It'd severely impact the user's experience, maintenance costs, and size of any given client.
(even if you had an operation with only 2 request media types, 2 response media types, and a differentiation between 204 and 201, it'd lead to have 8 execution methods, and the 8 corresponding generation methods).
It's also unlikely that any client application will need to use ALL the variations since in most cases those are variations on different formats supported by the API.
Alternative approaches include:

• use of the structured mime types parameter to exclude the undesirable scenarios
• use of the path filtering to exclude the problematic operation when it's not needed
• generating multiple clients
• use of OpenAPI overlays
• (a combination of the above)

For all those reasons, we've decided to leave it, about 2 years ago, to test if any customer demand would manifest, and you're the first to request it in that time.

We're unlikely to implement that feature request unless we get overwhelming additional demand for it.

Let us know if you have any additional comments or questions.