Challenges with Request object only mapping to one content type

[darrelmiller]

There is a concern that this will create a lot of redundancy in request objects where an API accepts multiple media types.

Do recent APIs use the pattern of accepting application/json and application/xml?

How often do APIs accept multiple media types in a request body and have the same set of responses.

There are APIs that accept JSON and protobuf.

What about APIs that accept multiple image types?

Could this work?

openapi: 4.0.0
paths:
  "transform":
    requests:
      acceptTheJpegorPng:
        parameterSchema:
          header:
            content-Type:   
              enum:
                - image/jpeg
                - images/png
      responses:
        responseToJpegOrPng:
            statusCode:  201
    pathResponses:
      badRequest:
        statusCode: 404
    

openapi: 4.0.0
paths:
  "transform":
    requests:
      acceptTheJpegorPng:
        contentType: ["image/jpeg","images/png"]
      responses:
        responseToJpegOrPng:
            statusCode:  201
    pathResponses:
      badRequest:
        statusCode: 404
    

[kevinswiber]

In OpenAPI <4.0.0, content-type is considered a special header that shouldn't be modeled directly. I do think having multiple content types on a single request could get tricky for tooling that parses HTTP request/response pairs from OAS and augments them with example data. Each example would have to specify its associated content-type(s), as well.

[mkistler]

I think allowing a request to specify multiple content types is a good solution to the redundancy problem. That is, requests that differ only in the contentType of the body can be more concisely described. The API designer still has the ability to use multiple requests whenever other aspects differ, so there are not downsides to this change that I can see.

[ralfhandl]

And while we are at it we may round off the XML support, see for example OAI/OpenAPI-Specification#630 (comment).