Forum Discussion

adarling's avatar
adarling
New Contributor
4 years ago
Solved

Changing API Response Based on Query Parameter

Hi all, I'm trying to figure out if it's possible to specify different API behaviors for a single endpoint with the Swagger editor based on query parameter provided?

I'm looking at and endpoint like this:
/processes/{processId}?detail={detailLevel}

 

where {processId} is an integer and {detailLevel} is a string enum between "summary" and "robust".

 

The robust response would look something like this

robustResponse = {
  "name": "mt-olympus"
  "macAddress": "ABC123",
  "status": unreachable,
  "timezone": "America/New_York",
  "osName": "Microsoft FooBar",
  "osVersion": "6.1.2",
}


And the summary response would look more like this:

simpleResponse = {
  "name": "mt-olympus",
  "statusColor": "red"
}

 

What I would like to do is specify two types of response objects, and return them based on query parameter of the request. I don't want to use different API endpoints, because both of these responses are querying the same source of data.

 

My question is: how do I define API responses that change based on query parameters in the Swagger editor (or in an openAPI spec generally?)

 

Alternatively, this may be an XY question. Should I just write 2 separate API endpoints to handle this?

  • Currently, OpenAPI does not allow distinguishing calls using query parameters. It's a future enhancement that's being considered.

2 Replies

  • Currently, OpenAPI does not allow distinguishing calls using query parameters. It's a future enhancement that's being considered.