Representing and exposiong block-out times and availability periods for a showable property.

Last update Nov 4, 2022 DR

STATUS: Stable

Restrictions and Availabiilty

Adding Restrictions to a Registration

When you request a registration on a listing, two of the fields available to you are restrictionsList and recurringRestrictionsList:

  "restrictionsList": [
    {
      "startDatetime": "2022-11-01T19:26:09.035-06:00:00",
      "endDatetime": "2022-11-01T22:26:09.035-06:00:00"
    }
  ],
  "recurringRestrictionsList": [
    {
      "daysOfWeek": "Sunday",
      "effectiveBeginDate": "2022-09-01T19:26:09.035-06:00:00",
      "effectiveEndDate": "2022-11-01T19:26:09.035-06:00:00",
      "startTime": 0830,
      "endTime": 1330
    }
  ]

These two JSON objects are how individual restrictions and recurring restrictions are represented throughout the application.

A one-shot restriction simply contains a pair of dateTimeOffset values to start and end the restriction.

A recurring restriction contains a startTime and endTime value, a day of the week (or comma-separated list of days of the week), and a pair of dateTimeOffsets to express the beginning and end date of the weeks to copy this recurring restriction to. We throw away the time portion of those values, just using the timezone segment to resolve when the day begins in your local time.

The format of the start and end times in a recurringRestriction are 4-digit integers expressing a military time in HHMM. The day runs from 0000 to 2359. There is no such time as 1460.

Adding and Editing Restrictions

Restrictions and Recurring Restrictions can be added, updated, and deleted with a series of endpoints. Because the payload shapes are differen for the two restriction types, separate POST and PUT endpoints were created to handle each of them:

POST /api/v1/registrations/{registrationId}/createRestriction
POST /api/v1/registrations/{registrationId}/createRecurringRestriction
PUT  /api/v1/restrictions/{restrictionId}/restriction
PUT  /api/v1/restrictions/{restrictionId}/recurringRestriction
DELETE /api/v1/restrictions/{restrictionId}

Availability

A listing's availability for scheduling can be fetched at:

GET /api/v1/registrations/{registrationId}/availability?showDate=[dateTimeOffset]

This endpoint will return a list of available time slots--essentially the inverse of the restrictions that have been applied on the registration:

      "listingAvailabilities": [
        {
          "startTime": "0000",
          "endTime": "0000"
        }
      ]

The availability times will be in the same 4-digit integer military time format as used for recurring restrictions.