Skip to content

Reservation API reference

Version: v0.44.0

The Reservation API (services.opencui.reservation.IReservation) is designed for booking scenarios, and provides functionality for creating, querying, and canceling reservations. This API exposes most of the features available in the reservation scenario.

  • To utilize this service, ensure that you have an existing provider that implements it.
  • To invoke this service, make sure you import it into your project and add a corresponding service slot within your target skill/frame type.

LocationName

The name of the location that can be displayed to customers.

ResourceName

The name of the bookable resource that can be displayed to customers.

ResourceType

The type of the bookable resource that can be displayed to customers.

Location

The places where bookable resources are located, such as restaurants, hotels, or hair salons.

  • Fields

    PropertyTypeDescription
    idkotlin.StringThe unique id for the location.
    nameLocationNameThe location name as seen by customers, must be unique.
    timezonejava.time.ZoneIdThe timezone of the location.
  • Methods

    MethodDescription
    listLocationReturns a list of locations for the reservation services.

listLocation

Returns a list of locations for the reservation services.

  • Parameters

    No parameters

  • Return

    If successful, this method returns a list of locations in the response body.

    TypeDescription
    Location[]A list of locations.
  • Code example

    kotlin
    val locationList = listLocation()

Resource

The bookable resources for customers, such as tables in a restaurant, doctors in a hospital, hairdressers in a hair salon, etc. Resource object is an abstract object.

  • Fields

    PropertyTypeDescription
    idkotlin.StringThe unique ID for the bookable resource.
    typeResourceTypeThe type of the bookable resource.
    nameResourceNameThe display name of the bookable resource.
    durationskotlin.Int[]The durations of the Resource.
    timezonejava.time.zoneIdThe timezone of the resource.
  • Methods

    MethodDescription
    getResourceInfoGets information about one Resource based on resource id.
    listResourceReturns a list of resources on the specified type for one location.
    resourceAvailableChecks whether there are available resources and returns ValidationResult.

getResourceInfo

Gets information about one resource based on resource id.

  • Parameters

    LabelTypeDescription
    resourceIdkotlin.StringRequired. The unique id of the resource to retrieve.
  • Return

    If successful, the response body contains an instance of resource. When no one matches, it returns null.

    TypeDescription
    ResourceThe details of the instance of the resource's subclass, based on the resource id.
  • Code example

    kotlin
    val resource = getResourceInfo("resource id")

listResource

Returns a list of resources on the specified type for one location.

  • Parameters

    LabelTypeDescription
    locationLocationRequired. The specified place that owns resources.
    typeResourceTypeRequired. The type of resource to retrieve.
    durationkotlin.intRequired. The duration of the resource to retrieve.
    datejava.time.LocalDateOptional. The date of resources to retrieve.
    timejava.time.LocalTimeOptional. The time of resources to retrieve.
  • Return

    If successful, this method returns a list of resources. If not found, it returns null.

    TypeDescription
    Resource[]A list of resources that matches the specified parameter value in the request.
  • Code example

    kotlin
    val location = listLocation().first()
    val resourceType = ResourceType("table")
    val date = LocalDate.of(2023, 2, 20)
    val time = LocalTime.of(14, 0, 0, 0)
    val duration = 3600
    
    val resourceList = listResource(location, resourceType, date, time, duration)

resourceAvailable

Checks whether a specified resource is available.

  • Parameters

    LabelTypeDescription
    resourceResourceRequired. The resource to retrieve.
    durationkotlin.intRequired. The duration of the resource to retrieve.
    datejava.time.LocalDateOptional. The date of the resource to retrieve.
    timejava.time.LocalTimeOptional. The time of the resource to retrieve.
  • Return

    TypeDescription
    ValidationResultThe result shows whether the resource is available.
  • Code example

    kotlin
    val location = listLocation().first()
    val resourceType = ResourceType("table")
    val date = LocalDate.of(2023, 2, 20)
    val time = LocalTime.of(14, 0, 0, 0)
    val duration = 3600
    val resource = listResource(location, resourceType, date, time, duration).first()
    
    val result = resourceAvailable(date, time, duration, resource)

Date

availableDates

Returns a list of available dates for a specified resource.

  • Parameters

    LabelTypeDescription
    resourceResourceRequired. The specified resource to retrieve.
    durationkotlin.intRequired. The duration of the resource to retrieve.
    timejava.time.LocalTimeOptional. The time of the resource to retrieve.
  • Return

    TypeDescription
    java.time.localDate[]A list of available dates on the specified resource that match the specified parameter value in the request.
  • Code example

    kotlin
    val location = listLocation().first()
    val resourceType = ResourceType("table")
    val time = LocalTime.of(14, 0, 0, 0)
    val duration = 3600
    val resource = listResource(location, resourceType, null, time, duration).first()
    
    val dateList = availableDates(time, duration, resource)

Time

availableTimes

Returns a list of available times for a specified resource.

  • Parameters

    LabelTypeDescription
    resourceResourceRequired. The specified resource to retrieve.
    durationkotlin.intRequired. The duration of the resource to retrieve.
    datejava.time.LocalDateOptional. The date of the resource to retrieve.
  • Return

    TypeDescription
    java.time.localTime[]A list of available times on the specified resource that match the specified parameter value in the request.
  • Code example

    kotlin
    val location = listLocation().first()
    val resourceType = ResourceType("table")
    val date = LocalDate.of(2023, 2, 20)
    val duration = 3600
    val resource = listResource(location, resourceType, date, null, duration).first()
    
    val timeList = availableTimes(date, duration, resource)

Reservation

The customer's booking for a resource at a specific location. Each reservation is a unique booking created by a customer.

  • Fields

    PropertyTypeDescription
    idkotlin.StringThe unique id of the reservation.
    resourceIdkotlin.StringThe id of the booked resource.
    userIdkotlin.StringThe unique id of the customer associated with the reservation.
    startjava.time.OffsetDateTimeThe start date and time of the reservation.
    endjava.time.OffsetDateTimeThe end date and time of the reservation.
    offsetkotlin.IntThe timezone offset.
  • Methods

    MethodDescription
    makeReservationCreates a new reservation for a customer.
    listReservationReturns a list of reservations for a specified customer.
    cancelReservationDeletes a specified reservation.
    updateReservationnUpdates a specified reservation.
    reservationCancelableChecks whether a specified reservation can be cancelled.
    reservationUpdatableChecks whether a specified reservation can be updated.

makeReservation

Creates a new reservation for a customer.

  • Parameters

    LabelTypeDescription
    userIdkotlin.StringRequired. The unique ID of the customer.
    resourceResourceRequired. The resource to be reserved.
    durationkotlin.intRequired. The duration of the resource.
    datejava.time.LocalDateOptional. The date of the reservation.
    timejava.time.LocalTimeOptional. The time of the reservation.
  • Return

    If successful, this method returns a reservation in the response body. Otherwise, null is returned.

    TypeDescription
    ReservationA reservation instance created by the customer.
  • Code example

    kotlin
    val location = listLocation().first()
    val resourceType = ResourceType("table")
    val date = LocalDate.of(2023, 2, 20)
    val time = LocalTime.of(14, 0, 0, 0)
    val duration = 3600
    val resource = listResource(location, resourceType, date, time, duration).first()
    
    val reservation = makeReservation("TestUser", date, time, duration, resource )

listReservation

Returns a list of reservations for a specified customer.

  • Parameters

    LabelTypeDescription
    userIdkotlin.StringRequired. The unique id of the customer.
    locationLocationOptional. The location of the reservations to retrieve.
    resourceTypeResourceTypeOptional. The resource type of the reservations to retrieve.
  • Return

    If successful, this method returns a list of reservations in the response body.

    TypeDescription
    Reservation[]A list of reservations matching the request criteria.
  • Code example

    kotlin
    val location = listLocation().first()
    val resourceType = ResourceType("table")
    
    val reservationList = listReservation("TestUser", location, resourceType)

cancelReservation

Cancel a reservation that was previously made by a customer.

  • Parameters

    LabelTypeDescription
    reservationReservationRequired. The reservation to be cancelld.
  • Return

    TypeDescription
    ValidationResultThe result shows whether the reservation was cancelled.
  • Code example

    kotlin
    val location = listLocation().first()
    val resourceType = ResourceType("table")
    val reservaion = listReservation("TestUser", location, resourceType).first()
    
    val result = cancelReservation(reservation)

updateReservation

Update a reservation that was previously made by a customer.

  • Parameters

    LabelTypeDescription
    reservationreservationRequired. The specified reservation to be updated.
    resourceResourceRequired. The resource of the reservation.
    durationkotlin.intRequired. The resource duration of the reservation.
    datejava.time.LocalDateOptional. The date of the reservation.
    timejava.time.LocalTimeOptional. The time of the reservation.
  • Return

    TypeDescription
    ValidationResultThe result shows whether the reservation was updated.
  • Code example

    kotlin
    val location = listLocation().first()
    val resourceType = ResourceType("table")
    val reservaion = listReservation("TestUser", location, resourceType).first()
    val date = LocalDate.of(2023, 2, 20)
    val time = LocalTime.of(14, 0, 0, 0)
    val duration = 3600
    val resource = listResource(location, resourceType, date, time, duration).first()
    
    val result = updateReservation(reservation, date, time, duration, resource)

reservationCancelable

Checks whether a particular reservation can be cancelled.

  • Parameters

    LabelTypeDescription
    reservationReservationRequired. The reservation to check for cancellation.
  • Return

    TypeDescription
    ValidationResultThe result shows whether the reservation is cancelable.
  • Code example

    kotlin
    val location = listLocation().first()
    val resourceType = ResourceType("table")
    val reservation = listReservation("TestUser", location, resourceType).first()
    
    val result = reservationCancelable(reservation)

reservationUpdatable

Checks whether a particular reservation can be updated.

  • Parameters

    LabelTypeDescription
    reservationreservationRequired. The reservation to check for update.
    resourceResourceRequired. The resource of the reservation.
    durationkotlin.intRequired. The resource duration of the reservation.
    datejava.time.LocalDateOptional. The date of the reservation.
    timejava.time.LocalTimeOptional. The time of the reservation.
  • Return

    TypeDescription
    ValidationResultThe result shows whether the reservation is updatable.
  • Code example

    kotlin
    val location = listLocation().first()
    val resourceType = ResourceType("table")
    val reservaion = listReservation("TestUser", location, resourceType).first()
    val date = LocalDate.of(2023, 2, 20)
    val time = LocalTime.of(14, 0, 0, 0)
    val duration = 3600
    val resource = listResource(location, resourceType, date, time, duration).first()
    
    val result = reservationUpdatable(reservation, date, time, duration, resource)

ValidationResult

The outcome of the verification or operation.

PropertyTypeDescription
successkotlin.BooleanA boolean value indicating the success or failure.
invalidFeatureKeyskotlin.String[]A list of invalid feature keys, if any.
messagekotlin.StringAn error message of the invalid feature.

Last updated: