Specifying RESTful API Response Based on Query Parameter in openAPI

Question

I am designing an openAPI specification for a project. The project is a REST API that provides information about hotels.

I want to either provide detailed information about the hotel, or a quick summary. My understanding of REST is that, since both of these relate to the same object in my data store, I should be using a query parameter to request the different data types.

So what I am looking for is a way to specify different API behaviors based on query parameters of a given request. Here is my current implementation. I am looking at an endpoint like this:

/hotels/{hotelId}?detail={detailLevel}

where {hotelId} is an integer and {detailLevel} is an optional string enum that can either be summary or robust.

If detail=robust, the response should look something like this:

{
  "name": "Hilton Grand Vacations on the Las Vegas Strip"
  "streetAddress": "2650 Las Vegas Blvd S",
  "city": "Las Vegas",
  "state": "NV",
  "zipCode": 89109
  "rating": 4.4,
  "minimumPrice": 125,
  "availableRooms": 10,
}

If detail=summary, the response should look something like this:

{
  "name": "Hilton Grand Vacations on the Las Vegas Strip",
  "rating": 4,
  "zipCode": 89109,
  "available": true
}

I don't want to have a specification that covers both of these responses, because I want to make it easy to validate any given response based on its URL parameter (for example, "available" should not be a field when detail=robust). So far, I have not been able to find a way to specify different return behaviors in openAPI based on query parameters.

Is there a way to specify behavior based on query parameters? Alternatively, should I change my API endpoint to something like /hotels/{hotelId}/{detailLevel}?

I am not sure though, will MatrixVariables be useful in anyway? — raj240
– raj240, Commented Sep 1, 2020 at 13:56

Taycan · Accepted Answer · 2020-09-01 13:53:44Z

8

To my disappointment, I have learned that openAPI does not support to use of query parameters to differentiate endpoints with the same path.

I will be specifying my paths as /hotels/{hotelId}/{detailLevel} instead.

answered Sep 1, 2020 at 13:53

Taycan

1951 silver badge10 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

Mohammad Jawad Barati Over a year ago

Nice reference. BTW I'd like to mention that this is my issue too, sometimes I think I need to use graphql instead of restful api. But I am not sure anyway.

Collectives™ on Stack Overflow

Specifying RESTful API Response Based on Query Parameter in openAPI

1 Answer 1

1 Comment

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

1 Comment

Your Answer

Sign up or log in

Post as a guest

Related