5.a. Implement Booking server: API (you) - Order-Based Booking

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

Implement a REST API interface

Implement an API 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 methods. 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.

API v3

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

DOWNLOAD THE SERVICE DEFINITION

API resources

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

  • TicketType: Ticket types must be provided in the services feeds in order to enable ordering multiple tickets for a service slot.
  • LineItem: a line item, which contains ordered tickets for a single service in a single time slot.
  • Order: order for a list of line items

Methods

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

Method HTTP Request
HealthCheck GET /v3/HealthCheck/
CheckOrderFulfillability POST /v3/CheckOrderFulfillability/*
CreateOrder POST /v3/CreateOrder/*
ListOrders POST /v3/ListOrders/*

Flow: create an order

Figure: Create an Order

Before an order is created, when the user adds new items to their pending order, Google will send the partner CheckOrderFulfillability requests to check whether the pending order in its current state can be fulfilled, in order to communicate any errors to the user in a timely manner. Potential order fulfillability errors are defined in Order Fulfillability, and the partner can also optionally send updated availability and pricing information in CheckOrderFulfillability responses.

When creating an order, Google will send the partner the user's given name, surname, phone number, and email. The email corresponds to 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 order should be shown to the partner's merchants in their system just like orders 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 important that your server has a valid TLS certificate matching its DNS name.

In order to authenticate the calling party requests will be sent in basic authetication 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.

Skeleton Implementation in Java

To get started, we provide a skeleton Booking server written in Java that can be compiled and installed. Check it out under maps-booking / java-maps-booking-rest-server-v3-skeleton. This server has stubbed out REST methods that are needed to support the integration, including authentication.

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 an order (see the Order Failure section of the Order specification, 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 Order Failure, and returned in the HTTP response. Business logic errors may be encountered when creating or a resource, for instance, in handling the CreateOrder method. Examples include, but are not limited to:

  • ORDER_UNFULFILLABLE is used if the requested order is no longer fulfillable, for example, if the number of tickets requested for a slot exceeds the number of tickets remaining, or if the price of the requested service has changed.
  • 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 request if no response is received. For this reason, CreateOrder calls must be idempotent. Requests include idempotency tokens that uniquely identify the request, and allow the partner to distinguish between a retried REST call and a separate order request.

Examples include but are not limited to:

  • A successful CreateOrder HTTP response includes the created order. If the exact same CreateOrder request is received a second time (including idempotency_token), then the same CreateOrderResponse has to be returned. No second order is created and the user, if applicable, is charged exactly once. Note that if a CreateOrder attempt fails, the partner backend should retry if the same request is sent again.

Have questions?

Be sure to check out our FAQs.

Next step

NEXT STEP: Test implementation (both)