5. Implement Booking server: API v3 (you)

Setting up a Booking server on your end will allow Reserve with Google to create appointments / bookings / reservations with you on behalf of the user.

Refer to the Partner Portal documentation to learn how to configure the connection to your sandbox and production booking servers.

Implement a REST API interface

Implement an API interface based on REST. This allows Google to send booking requests as SSL HTTP requests.

We ask our new partners to implement a recommended set of API v3. Partners may select whichever URL and port works best for their infrastructure.

We recommend that you first set up a QA / sandbox booking server that we can connect to our sandbox environment and then only move to a production environment once the sandbox server has been fully tested.

Optionally, you can download the service definition in proto format below to get started with the API implementation.

DOWNLOAD THE SERVICE DEFINITION

Methods

The following API methods are required to be implemented on your end for the Booking server:

Method HTTP Request
HealthCheck GET /v3/HealthCheck/
CheckAvailability POST /v3/CheckAvailability/
CreateBooking POST /v3/CreateBooking/
UpdateBooking POST /v3/UpdateBooking/
GetBookingStatus POST /v3/GetBookingStatus/
ListBookings POST /v3/ListBookings/

API resources

Please familiarize yourself with the following resource types that will be utilized in this implementation:

  • Slot: an inventory slot
  • Booking: appointment for an inventory slot

Flow: create a booking

Figure: Create a Booking from a Slot

When creating a booking, Google will send the partner the user's given name, surname, phone number, and email. The email corresponds with the user's Google account and can be treated as a unique identifier. This should be treated as a guest checkout from the partner's point of view as Reserve with Google has no way to look up the user's account in the partner's system. The final booking should be shown to the partner's merchants in their system just like bookings that come for the partner's booking system.

Security and Authentication

All communication to your Booking server is going to be over HTTPS, so it is essential that your server has a valid TLS certificate matching its DNS name. We recommend to use one of the freely available SSL/TLS verification tools for your server setup, e.g. Qualys' SSL Server Test.

In order to authenticate the calling party, requests will be sent in basic authentication with a username and password, which you provided to us in the onboarding form. Should you need to update these credentials, you can contact us via email or resubmit the form.

Sample Skeleton Implementations

To get started, we provide sample skeletons of a Booking Server written for Node.js and Java frameworks. Check them out under maps-booking repository:

These servers have stubbed out REST methods that are required to implement the API v3 interface for booking- or order-based integrations.

Requirements

HTTP errors and business logic error

Two types of errors may occur when a partner backend handles HTTP requests: unexpected errors that arise from incorrect data; and business logic errors that indicate inability of creating or updating a booking (see Booking Failure), e.g., if the requested slot is unavailable.

Unexpected errors, if encountered, should be returned to the client using standard HTTP error codes. You can see the full HTTP status code list.

On the contrary, business logic errors should be captured in Booking Failure, and returned in HTTP response. Business logic errors may be encountered when creating or updating a resource, i.e., in handling method CreateBooking, and UpdatingBooking. Examples include but are not limited to:

  • SLOT_UNAVAILABLE is used if the requested slot is not longer available.
  • PAYMENT_ERROR_CARD_TYPE_REJECTED is used if the provided credit card type is not accepted.

Idempotency

Communication over the network is not always reliable and Google Reserve may retry REST HTTP requests if no response is received. For this reason, all methods that mutate state (CreateBooking, UpdateBooking) have to be idempotent. Request messages for CreateBooking include idempotency tokens to uniquely identify the request and allow the partner to distinguish between a retried REST call (with the intent to create a single booking) and two separate bookings. UpdateBooking should naturally be idempotent, so no idempotency token is used for requests to UpdateBooking.

Examples include but are not limited to:

  • A successful CreateBooking HTTP response includes the created booking and, in some cases, payment is processed as part of the booking flow. If the exact same CreateBookingRequest is received a second time (including idempotency_token), then the same CreateBookingResponse has to be returned. No second booking is created and the user, if applicable, is charged exactly once. Note that if a CreateBooking attempt fails, the partner backend should retry if the same request is sent again.

Idempotency requirement applies to all methods that contain idempotency tokens.

Other versions

For documentation for other versions of the API, see the following pages:

Next step

NEXT STEP: Test implementation (both)