Forum Discussion

Olumide's avatar
Olumide
New Contributor
5 years ago

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

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.

OpenApi
    • Olumide's avatar
      Olumide
      New Contributor
      5 years ago

      Thanks for your reply.

       

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

       

      • RonRatovsky's avatar
        RonRatovsky
        Staff
        5 years ago

        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.