[Question] Optional response payloads

[jdegre]

Hi,
How to express in OpenAPI that a response payload is optional for a given HTTP response code?

I noticed that the keyword "required: true/false" is applicable only to Request Body Object, but not to Response Body Object.

So, if a Response Body Object has a "content" field, does it indicate that a response payload is mandatory, and receiving an empty payload is considered as not allowed?

My goal is to express that a given HTTP response (mainly error codes, 4xx, 5xx) can be sent with, or without response payload. Per RFC 7231, the presence of response payloads in these error codes is encouraged (should) but it's not really mandated.

Thanks!
/Jesús.

[aghorpade]

@jdegre - It's always a good practice to put response payload in case of success(2xx) or error scenario(4xx,5xx) which clearly indicate what is happening and makes your api specification with futuristic vision.
To answer optional response object you can take a look at last section of response object in given link -
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#responsesObject
which says description is required while content/body is mandatory and you can skip that

Do you still looking to keep response payload empty or optional in case of error scenario?

[jdegre]

hi @aghorpade; thanks for the reply!

i agree it's a good practice to have response payloads in case of error scenarios, no doubt. i guess that's why the RFCs indicate that a response payload should be included (e.g. RFC 7231, section 6.6).

however, it is often the case where a given response message can be sent back without a response body and, per HTTP RFCs, that should be a perfectly legal message, that the recevier should be expected to act upon (and not consider it as a malformed response message).

so, i wonder if OpenAPI can express such case, in which a response payload is simply defined as optional in the response. so far, I have not managed to figure out how.

[aghorpade]

@jdegre As I mentioned, it is possible with OAS. I just tried with one sample example , refer below one.

{
  "openapi": "3.0.0",
  "info": {
    "title": "NoResponseApi",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "localhost:8080"
    }
  ],
  "produces": [
    "application/json"
  ],
  "schemes": [
    "HTTP"
  ],
  "paths": {
    "/products": {
      "post": {
        "operationId": "create product",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "example": {
                  "strict": true,
                  "value": {
                    "type": "plastic"
                  }
                },
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "no response body"
          }
        }
      }
    }
  }
}

[jdegre]

@aghorpade, I think that you have mixed a bit the syntax of OpenAPI 2.x and 3.x in your example... but anyway, I suppose the important point is in:

      responses:
        '200':
          description: no response body

This part achieves the intent of not requiring anything about the response body, so it allows to have a response with, or without it; that's ok.

However, it makes it impossible to specify a given media type, and the schema of its content, in case the response body is effectively present.

So, as soon as you write;

      responses:
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

Does it make the response body as required/mandatory the response? (so the response message can be considered as valid and well-formed)
If so, this excludes the possibility to have a valid response message without a response body.

[aghorpade]

@jdegre - as soon as you keep content-type and schema for response body then it becomes mandatory to send that type of response.

[jdegre]

@jdegre - as soon as you keep content-type and schema for response body then it becomes mandatory to send that type of response.

yeap, that's also my assumption (even though the normative text of OpenAPI 3.x does not really say so very clearly).

but that's the whole point for opening this issue; personally, i think it would be good to support the possibility to specify that a given response message can have no response payload (as allowed by the HTTP RFCs) and, optionally, it may also have a certain payload compliant with a given schema.

that's not possible today in OpenAPI 3.0.x so, in the APIs I am working with, we need to resort to external documentation to make it clear that such behaviour is indeed allowed by the API.

[karenetheridge]

I address the concepts of optional, required-empty, required-not-empty response payloads here: karenetheridge/OpenAPI-Modern#25