cancel
Showing results for 
Search instead for 
Did you mean: 

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

SOLVED
Highlighted
New Contributor

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.

Tags (1)
1 ACCEPTED SOLUTION

Accepted Solutions
Highlighted
Moderator

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

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.


Did my reply answer your question? Give Kudos or Accept it as a Solution to help others.↓↓↓↓↓

View solution in original post

3 REPLIES 3
Highlighted
Moderator

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

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.


Did my reply answer your question? Give Kudos or Accept it as a Solution to help others.↓↓↓↓↓

View solution in original post

Highlighted
New Contributor

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

Thanks for your reply.

 

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

 

Highlighted
Moderator

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

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.


Did my reply answer your question? Give Kudos or Accept it as a Solution to help others.↓↓↓↓↓
New Here?
Join us and watch the welcome video:
Announcements
Top Kudoed Authors