Spec'ing an endpoint that returns different responses depending on params sent

[Olumide]

I am new to openapi and am evaluating it in order to spec a REST API characterized by endpoints that return different(ly structured) responses depending on which query parameters are sent to the server. I have been tasked with extending one such API (not written by myself).

For example, let's say an endpoint www.acme.com/gizmo supports 6 query parameters param1, param2, ..., param6. If the odd-numbered params (param1, param3, param5) are initialized the server responds with the XML message <foo>...</foo>. However if the even-numbered params (param2, param4, param6)  are initialized the server responds with the XML message <bar>...</bar> etc.

Frankly, I don't think this is a good design (or is it?) but the API has been shipped and customers are using it.  What I'd like to know if whether openapi can be used to spec such an endpoint.

[RonRatovsky · Accepted solution]

At the moment, the OpenAPI does not allow separating responses based on query parameters.

There should be an open issue for it at https://github.com/OAI/OpenAPI-Specification/, though I can't find it at the moment.

[Olumide]

Thanks for your reply.

Do you think such an endpoint design breaks any principles of good REST APIs?

[RonRatovsky]

I do not. Just because something is not supported by the spec, it doesn't mean it's a bad practice. Whether it makes sense in your situation really depends on the use case.