Last modified: Mon Nov 04 2019 16:15:12 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. If a hotel uses Winding Tree Data Model, it should advertise a bookingUri in its published data. This bookingUri should be pointing to an instance of REST API which is implementing the booking protocol.

While setting up your server, don't forget about proper Cross-origin resource sharing (CORS) setup since the API might be called from various places. In an ideal setup, this won't be necessary, because the protocol would be used on a server to server level, not directly from the clients.

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.

Spam protection

You might have noticed that there is no way of protecting the API. With the introduction of ORG.ID, we have created a unique identity for every potential API caller, and with trust clues we have introduced a way of checking eligibility of an ORG.ID to call an API.

With combination with associatedKeys and request signing, every operator of a Booking API instance has the possibility of limiting it's API users only to trusted parties.

To prevent spamming, we recommend to accept only signed requests and to verify that the API callers fullfill some trust requirements. These can vary between Booking API operators.

Sample Booking API

We have a sample implementation in NodeJS alongside the Booking protocol specification with a very basic support of trust clues. 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.

Where to next