REST API Design for getting days without resource

Question

I have recently come across a design question and will explain it using an imaginary scenario:

Assume you need to retrieve the days where there are no bookings for a given date range. You could filter the results and manually identify what date is not contained, but you'd be getting the booking information unnecessarily, if all you're after is a list of dates without bookings.

/bookings?startDate=x&endDate=y

Returns

{
 "id": 1,
 "title": "mybooking",
 "bookingdate": "2018-01-15T16:18:44.258843Z"
}

Would such a scenario require a new resource as below?

/freedays

Returns:

[
 "2018-01-15T16:18:44.258843Z",
 "2019-01-15T16:18:44.258843Z"
]

As the response schema is different, compared to a booking response, I think a filter on the bookings resource would not be applicable for this scenario.

What would be a good rest design for the above use case?

Thanks

Answer 1

On the REST side of your application, asking for the days (or timeslots) without bookings is indeed a different resource than asking for the bookings themselves.

Thus, the two resources

/bookings?startDate=x&endDate=y
/freedays?startDate=x&endDate=y

would return completely different sets of information.

On the database side, both resources can probably obtain their information from one table (or one set of tables).
This clearly illustrates that any correspondence between a REST resource and a database table is more coincidence than design.

• neilsimp1: This clearly illustrates that any correspondence between a REST resource and a database table is more coincidence than design. I really love this sentence.