Last modified: Thu Apr 18 2019 08:29:10 GMT+0000 (Coordinated Universal Time)

How to accept bookings?

In this tutorial, you will learn about the booking process in Winding Tree ecosystem.

Requirements

Step by step

Booking in Winding Tree ecosystem is done in a decentralized way. Every hotel should advertise a bookingUri in its data published through Write API. This bookingUri should be pointing to REST API which is implementing the booking protocol.

Booking protocol

The booking protocol is really just a description of the REST API. It currently contains an endpoint to create new booking and an endpoint to cancel an existing one.

Because this booking scheme is totally decentralized, stateless and may be quite disconnected in time from the actual offer published on Winding Tree, the booking request should contain all of the data that the traveller and the provider agree on.

First, it contains information about the customer itself. Optional fields include a postal address and phone. It is absolutely necessary that the provider gets a means of contact with the actual customer.

{
  "customer": {
    "name": "Elizabeth",
    "surname": "Crown",
    "email": "[email protected]"
  }
}

Then there's the information about the booking itself. It contains mainly information about the guests and which rooms were booked. It is even ready for allocating guests into particular rooms.

{
  "booking": {
    "arrival": "2019-02-03",
    "departure": "2019-02-10",
    "guestInfo": [
      {
        "id": "guest-0", "name": "Elizabeth", "surname": "Crown", "age": 25
      },
      {
        "id": "guest-1", "name": "Philip", "surname": "Crown", "age": 30
      }
    ],
    "rooms": [
      {
        "id": "room-1",
        "guestInfoIds": ["guest-0", "guest-1"]
      }
    ]
  }
}

And finally the information about the price that the guest is proposing to the hotel. Apart from the total price, this also contains information about possible cancellation fees. A hotel can refuse to accept the booking if the submitted price is just not acceptable.

{
  "pricing": {
    "currency": "EUR",
    "total": 100,
    "cancellationFees": [
      {
        "from": "2019-02-01",
        "to": "2019-02-03",
        "amount": 50
      }
    ]
  }
}

All of this information combined (also with the appropriate hotelId and an optional textual note) will be sent to the appropriate endpoint on the declared bookingUri.

{
  "customer": {
    "name": "Elizabeth",
    "surname": "Crown",
    "email": "[email protected]"
  },
  "booking": {
    "arrival": "2019-02-03",
    "departure": "2019-02-10",
    "guestInfo": [
      {
        "id": "guest-0", "name": "Elizabeth", "surname": "Crown", "age": 25
      },
      {
        "id": "guest-1", "name": "Philip", "surname": "Crown", "age": 30
      }
    ],
    "rooms": [
      {
        "id": "room-1",
        "guestInfoIds": ["guest-0", "guest-1"]
      }
    ]
  },
  "pricing": {
    "currency": "EUR",
    "total": 100,
    "cancellationFees": [
      {
        "from": "2019-02-01",
        "to": "2019-02-03",
        "amount": 50
      }
    ]
  }
}
$ curl -X POST https://hotel-booking.com/booking \
  -H 'Content-Type': 'application/json' \
  --data @booking.json

{
  "id": "some-booking-reference",
  "status": "confirmed"
}

The booking server should of course validate all of the incoming data and if the proposed conditions are OK with the hotel, it should accept the booking. It can either make it confirmed or just pending which means that there might be another process in place.

Sample Booking API

We have a sample implementation in NodeJS alongside the Booking protocol specification. It is definitely not meant for any production use, but merely as a demonstration of what should be going on in a custom implementation of Booking API.

If you already have a Booking system, it should be only a matter of implementing a data format adapter.

Where to next