# Calendar API

This group covers bookings guests made through booking pages, the caller's vacations and vacation requests, and the workspace's working calendar of work schedules and holidays. Every call acts as a person: send a personal access token, or an OAuth access token from a person's sign-in (scope `Volobox`). An integration app's own client secret is refused with `403` (`Volobox:Integrations:MemberConnectionRequired`). Paths, tokens and conventions are in [API overview](/docs/api-overview).

## Bookings

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/booking` | `calendar.booking.getList` | Lists the bookings the caller hosts or may see, one page at a time. |
| GET | `/api/v1/booking/{id}` | `calendar.booking.get` | Gets a booking the caller hosts or may see. |
| POST | `/api/v1/booking/{id}/cancel` | `calendar.booking.cancel` | Cancels a booking and tells the guest, with an optional reason. |
| POST | `/api/v1/booking/{id}/hand-over` | `calendar.booking.handOver` | Hands a booking over to another host of its booking page. |
| POST | `/api/v1/booking/{id}/no-show` | `calendar.booking.markNoShow` | Marks that the guest of a booking did not show up. |
| GET | `/api/v1/booking/by-meeting/{meetingId}` | `calendar.booking.findByMeeting` | Gets the booking behind a meeting, or nothing when the meeting was not booked. |

## Vacations

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/vacation` | `calendar.vacation.getList` | Lists the caller's own vacations in a date range, with their pending new requests. |
| POST | `/api/v1/vacation` | `calendar.vacation.create` | Books time off for the caller, or submits it for approval while approval is required. |
| GET | `/api/v1/vacation/{id}` | `calendar.vacation.get` | Gets one of the caller's own vacations. |
| PUT | `/api/v1/vacation/{id}` | `calendar.vacation.update` | Changes the caller's vacation, or asks for the change while approval is required. |
| POST | `/api/v1/vacation/{id}/cancel` | `calendar.vacation.cancel` | Cancels the caller's vacation, or asks for it to be cancelled while approval is required. |
| GET | `/api/v1/vacation/all` | `calendar.vacation.getAllList` | Lists the approved vacations of everyone in the workspace that overlap a date range. |
| GET | `/api/v1/vacation/upcoming/{userId}` | `calendar.vacation.getUpcomingForUser` | Gets a person's current or next vacation within the next 30 days, or nothing. |

Request bodies:

- `CreateVacationDto` (`create`): requires `endTime` (date-time), `startTime` (date-time), `typeId` (uuid).
- `UpdateVacationDto` (`update`): requires `endTime` (date-time), `startTime` (date-time), `typeId` (uuid).

## Vacation requests

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| PUT | `/api/v1/vacation-request/{id}` | `calendar.vacationRequest.update` | Changes the caller's own pending vacation request. |
| POST | `/api/v1/vacation-request/{id}/withdraw` | `calendar.vacationRequest.withdraw` | Takes back the caller's own pending vacation request. |
| GET | `/api/v1/vacation-request/mine` | `calendar.vacationRequest.getMine` | Lists the caller's own vacation requests, one page at a time. |

Request bodies:

- `UpdateVacationRequestDto` (`update`): requires `endTime` (date-time), `expectedRevision` (integer), `startTime` (date-time), `typeId` (uuid).

## Working calendar

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/working-calendar/holidays` | `calendar.workingCalendar.getHolidays` | Lists the holidays of a year, optionally for one country. |
| POST | `/api/v1/working-calendar/holidays` | `calendar.workingCalendar.createHoliday` | Adds a holiday, for working calendar managers. |
| PUT | `/api/v1/working-calendar/holidays/{id}` | `calendar.workingCalendar.updateHoliday` | Changes a holiday, for working calendar managers. |
| DELETE | `/api/v1/working-calendar/holidays/{id}` | `calendar.workingCalendar.deleteHoliday` | Deletes a holiday, for working calendar managers. |
| POST | `/api/v1/working-calendar/holidays/import` | `calendar.workingCalendar.importHolidays` | Imports a country's public holidays for a year, for working calendar managers. |
| GET | `/api/v1/working-calendar/schedules` | `calendar.workingCalendar.getSchedules` | Lists the workspace's work schedules. |
| POST | `/api/v1/working-calendar/schedules` | `calendar.workingCalendar.createSchedule` | Creates a work schedule, for working calendar managers. |
| PUT | `/api/v1/working-calendar/schedules/{id}` | `calendar.workingCalendar.updateSchedule` | Changes a work schedule, for working calendar managers. |
| DELETE | `/api/v1/working-calendar/schedules/{id}` | `calendar.workingCalendar.deleteSchedule` | Deletes a work schedule, for working calendar managers. |
| POST | `/api/v1/working-calendar/schedules/{id}/default` | `calendar.workingCalendar.setDefaultSchedule` | Makes a work schedule the workspace's default, for working calendar managers. |
| GET | `/api/v1/working-calendar/schedules/selectable` | `calendar.workingCalendar.getSelectableSchedules` | Lists the work schedules a person may choose for themselves. |

Request bodies:

- `CreateUpdateHolidayDto` (`createHoliday`, `updateHoliday`): requires `countryCode` (string), `name` (string).
- `CreateUpdateWorkScheduleDto` (`createSchedule`, `updateSchedule`): requires `name` (string).

## Example

`calendar.vacationRequest.getMine`: lists the caller's own vacation requests, one page at a time.

```bash title="curl"
curl -s "https://volobox.example.com/api/v1/vacation-request/mine?SkipCount=0&MaxResultCount=20" \
  -H "Authorization: Bearer $VOLOBOX_TOKEN"
```

`SkipCount` is how many items to skip and `MaxResultCount` how many to return. The answer carries `totalCount` and the page of `items`.
