CODEWITHSUNDEEP
restopenapi
Taycan
Taycan

Reputation: 195

Specifying RESTful API Response Based on Query Parameter in openAPI

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}?

Upvotes: 9

Views: 1904

Answers (1)

Taycan
Taycan

Reputation: 195

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.

Upvotes: 8

Related Questions