Allow for multiple response schemas for each response code

[aroemen]

Example

  responses:
    200:
      description: An array of events
      schema:
        type: array
        items:
          $ref: '#/definitions/Event'
    200:
      description: |
        An array of flattened events. This is the response
        object when singleEvents is True.
      schema:
        type: array
        items:
          $ref: '#/definitions/EventFlat'
    default:
      description: Unexpected error
      schema:
        $ref: '#/definitions/Error'

[webron]

I doubt we'll support that any time soon. One of the leading principles we have behind Swagger is API determinism. By saying that a single response may return various object types, that pretty much breaks that principle.

[theganyo]

Standing on idealism on this point can, ironically, lead to less determinism: Because Swagger doesn't allow multiple return values, one has to code APIs that need this capability to return generic responses.

[webron]

Generic responses don't necessarily mean less determinism (though they can, depending on the level of abstraction). That said, I could argue it may imply a faulty API design in general, in many case ;)

[theganyo]

You could. :) However, as I'm sure you're aware, that's a rigid and isolating argument that excludes Swagger from being able to support many APIs (and API styles) that exist in the real world.

[fehguy]

I do think it's worth exploring how it could be supported in the future. But I will add that, the goal of swagger is not to describe every single API case out there. Some will be left behind, for the sake of efficiency in the ones that we can support with a full toolchain.

[webron]

It's a matter of finding the balance between requirements, support, elegance and much more. The spec has evolved over the years and obviously supports today much more than it had initially.

My main concern with breaking away from the determinism principle is that it'll lead to changes all across the spec, and may increase its complexity substantially. This is not just an issue for the spec itself but also for the support tools. If we do it, we need to do it carefully and take it all under consideration.

[sebderenty]

Just to support this request.
In my API, the "get user" endpoint (GET /users/{user_id}) returns the User object if the requested user is the current user and it returns a smallest "PublicUser" object otherwise.
The format of the URL seems semantically correct for the two types of object returned.

[webron]

@sebderenty - But how would you "document" these two use cases? How can you generate both client and server code that can behave this way from a Swagger definition?

[dannylevenson-ps]

I have a similar problem/concern. We recently updated the version of swagger-tools we are using which moved us from version 1.2 of the Swagger schema to version 2.0. This caused my API spec to no longer validate correctly. I have a URL path that looks like this:

GET /quote/{citvId}/group/{groupId}

Since this is a front end for a third party service, the error information I am able to provide is quite different for an invalid/unrecognized citvId value versus an invalid groupId value. In either case, I need to return a 400 status code. I originally had my responses defined like this:

"responses": {
    "200": {
        "description": "Successful response",
        "schema": {
            "$ref": "#/definitions/GroupDetailed"
        }
    },
    "400": {
        "description": "Unrecognized quote or group ID",
        "schema": {
            "oneOf": [
                {
                    "$ref": "#/definitions/UnrecognizedQuoteId"
                },
                {
                    "$ref": "#/definitions/UnrecognizedGroupId"
                }
            ]
        }
    }

and in the definitions:

"UnrecognizedQuoteId": {
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "httpStatus",
                "dateTime",
                "enservioStatusCode",
                "enservioMessage"
            ],
            "properties": {
                "httpStatus": {
                    "type": "integer",
                    "description": "This will be 400 for this type of error"
                },
                "dateTime": {
                    "type": "string",
                    "description": "ISO format timestamp for request"
                },
                "serviceStatusCode": {
                    "type": "string",
                    "description": "Numeric status code returned by third party service (e.g. 1106)"
                },
                "serviceMessage": {
                    "type": "string",
                    "description": "Message from third party service"
                }
            }
        }
    }
},
"UnrecognizedGroupId": {
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "citvId",
                "httpStatus",
                "dateTime",
                "validation"
            ],
            "properties": {
                "citvId": {
                    "type": "string",
                    "description": "The citvId that was specified in the request."
                },
                "httpStatus": {
                    "type": "integer",
                    "description": "This will be 400 for validation errors"
                },
                "dateTime": {
                    "type": "string",
                    "description": "ISO format timestamp for request"
                },
                "validation": {
                    "type": "string",
                    "description": "Message indicating the unrecognized group ID"
                }
            }
        }
    }
},

Since responses no longer allow oneOf for the schema, I have had to collapse these two errors into a single error like this:

"responses": {
    "200": {
        "description": "Successful response",
        "schema": {
            "$ref": "#/definitions/GroupDetailed"
        }
    },
    "400": {
        "description": "Unrecognized citvId or groupId",
        "schema": {
            "$ref": "#/definitions/UnrecognizedQuoteOrGroupId"
        }
    }
}

with the definitions collapsed like this:

"UnrecognizedQuoteOrGroupId": {
    "required": [
        "error"
    ],
    "properties": {
        "error": {
            "type": "object",
            "required": [
                "httpStatus",
                "dateTime",
            ],
            "properties": {
                "citvId": {
                    "type": "string",
                    "description": "The citvId that was specified in the request in the case of a valid citvId but igroupId."
                },
                "httpStatus": {
                    "type": "integer",
                    "description": "This will be 400 for this type of error"
                },
                "dateTime": {
                    "type": "string",
                    "description": "ISO format timestamp for request"
                },
                "serviceStatusCode": {
                    "type": "string",
                    "description": "Numeric status code returned by third party service (e.g. 1106) for an invalid citvId"
                },
                "serviceMessage": {
                    "type": "string",
                    "description": "Message from third party service for an invalid citvId which translates to their risk ID"
                },
                "validation": {
                    "type": "string",
                    "description": "Message indicating the unrecognized groupId in the case of a valid citvId but igroupId"
                }
            }
        }
    }
},

My API is behaving in a completely deterministic manner. If the citvId is invalid, one type of error information is available. Alternatively, if the groupId is invalid, slightly different type of error information is available. In order to provide the various information in a single response definition, I have had to introduce ambiguity into my definitions by removing the uncommon properties from the required list and explaining when certain properties will be available in the response. In my opinion, this is less deterministic and more confusing than when oneOf was available to allow for multiple schemas for the 400 response.

I believe that restricting the responses to a single schema per status code is overly rigid and restrictive.

Please do not respond by simply saying, "I could argue it may imply a faulty API design in general" as you did to a previous post. If you feel that this API design is faulty, please explain the correct way to handle a situation like my case.

[webron]

@dannylevenson-ps - thank you for the elaborate use case, much appreciated.

To get it out of the way oneOf was never supported. It wasn't supported in 1.2 nor in 2.0. There may have been a bug in the JSON Schema which allowed for it in swagger-tools, but that does not mean it was supported. The source of truth is the spec itself and it's clear oneOf is not part of it.

You're right about the API behaving in a deterministic manner, but it behaves in a deterministic manner to the producer (i.e. the server). At the end of the day, the API (and its documentation) aim to serve the consumer (i.e. the client), and from the client's point of view, it's a non-deterministic behavior. The client has no way of knowing that citvId or groupId are invalid. Had it known that, I imagine it wouldn't have tried to invoke the API call in the first place - so it has no way of knowing what error to expect. In fact, by using oneOf, you're saying "you'll be getting this OR that" which is... non-deterministic.

If your errors had a shared property that has a unique value per error, that could have acted as a discriminator and you could have used inheritance to document it. Unfortunately, httpStatus in your example, while shared, has the same value for both errors.

I do have some ideas how to deal with situations that are not fully deterministic, but that's more of a general solution and not specific here. Unfortunately, it's far from being baked but I'll get around to it as well.

FWIW, the comment "I could argue it may imply a faulty API design in general" was a bit out of frustration and not directed at anyone in particular. I don't think it's our job here to comment on one API paradigm or the other. Just like anyone else, I have my opinions and can share them if asked, but telling people how to design their APIs is not within the scope of our work. As @fehguy mentioned, we're never going to cover all use cases, but we definitely want to expand the spec carefully to accommodate for more.

[dannylevenson-ps]

@webron - you said, "The client has no way of knowing what citvId or groupId are invalid. Had it known that, I imagine it wouldn't have tried to invoke the API call in the first place - so it has no way of knowing what error to expect."

In a perfect world, yes, the client would invoke this API if and only if it knew that both the citvId and groupId were valid. And, if that were true, my server code would not have to do parameter validation on the invocation for either parameter. However, in order to be robust, my server code must validate the multiple inputs for this call and the error responses need to be different depending on which value is invalid. I do not agree that this is non-deterministic from the client's point of view. If the client feeds the API an invalid citvId it gets one type of error response. If the client feeds the API an invalid groupId it gets a different type of error response. The only way it would be non-deterministic from the client's perspective is if the client could get either this or that given the same erroneous input for two different calls.

If the client is using the API properly, it should always have valid values for both, but it is unrealistic to state that a client will only ever invoke the API call with valid values for all input parameters.

[webron]

It's deterministic if you combine the error with the cause (as you mention above). Since there's no way to link the error to the cause, it's becoming an either/or situation. You know the link, but if, for example, there's an auto-generated client, who would it know how to handle it?

[mclate]

Also would vote for adding multiple responses with the same code. The best example would be any 400 (Bad request) error which can be caused by many reasons. Take in example validation errors: missing fields, extra fields passed or simply wrong data provided - these all are different errors grouped under the same status code where exact error is returned in response playload, which may vary for each situation. This is still considered as deterministic behaviour as it is uniquely defined in response playload.

[webron]

You can still document it, assuming you follow a common structure to all the errors (as you probably should).

[dannylevenson-ps]

I'm getting angry all over again. I agree with Jack and and disagree with Ron. Even if you use a common structure for all errors, there are going to be cases where more or different information is available based on the erroneous input. All bad requests need to return a 400; all bad requests do not have the same error response data.