Step 3: Implement the Waitlists booking server

You need to stand up a booking server to allow the Actions Center to make callbacks to create and update bookings on your behalf.

  • The Reservations Waitlists implementation. This is used when you participate in the Reservations Waitlists pilot program. This allows the Actions Center to retrieve wait estimates and create waitlist entries on behalf of the user.
  • The Standard implementation. This allows the Actions Center to create appointments, bookings, and reservations with you on behalf of the user. To implement a booking server for the Reservations End-to-End integration please refer to Implement the booking server.

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 server requests over HTTP.

To start, set up a development or sandbox booking server that can be connected to the Actions Center sandbox environment. Only move to a production environment once the sandbox server is fully tested.

Methods

For each type of booking server, a different set of API methods are required on your end. Optionally, you can download the service definition in proto format to get started with the API implementation. The following tables show the methods for each implementation and include links to the service proto formats.

Waitlist implementation
Waitlist service definition. Download the proto service definition file.
Method HTTP Request
HealthCheck GET /v3/HealthCheck/
BatchGetWaitEstimates POST /v3/BatchGetWaitEstimates/
CreateWaitlistEntry POST /v3/CreateWaitlistEntry/
GetWaitlistEntry POST /v3/GetWaitlistEntry/
DeleteWaitlistEntry POST /v3/DeleteWaitlistEntry/

API resources

Waitlist

The following resources are used to implement waitlist-based booking:

Flow: create a waitlist entry

This section covers how to create a booking for the Reservations Waitlists integration.

Figure 2: Workflow to create a waitlist entry
Figure 2: Workflow to create a waitlist entry

When the user creates a waitlist entry, Google sends you the user's given name, surname, phone number, and email. The email is the same as the user's Google account and is treated as a unique identifier. From your point of view, this waitlist needs to be treated as a guest checkout, because Reserve with Google can't look up the user's account in your system. Make sure the final waitlist entry appears identical to your merchants' entries that come from your waitlist system.

Security and Authentication

All communication to your booking server happens over HTTPS, so it's essential that your server has a valid TLS certificate that matches its DNS name. To help set up your server, we recommend the use of a freely available SSL/TLS verification tool, such as Qualys' SSL Server Test.

All requests Google will make to your booking server will be authenticated using HTTP basic authentication. The basic authentication credentials (username and password) for your booking server can be entered in the Booking Server Configuration page within the Partner Portal. Passwords must be rotated every six months.

Sample Skeleton Implementations

To get started, check out the following sample skeletons of a booking server written for Node.js and Java frameworks:

These servers have stubbed out REST methods.

Requirements

HTTP errors and business logic errors

When your backend handles HTTP requests, two types of errors may occur.

  • Errors related to infrastructure or incorrect data
  • Errors related to business logic
    • Return HTTP status code set to 200 OK, and specify the business logic failure in the response body. The types of business logic errors you can encounter are different for the different types of server implementations.

For the Reservations Waitlists integraton, business logic errors are captured in Waitlist Business Logic Failure and they're returned in HTTP response. Business logic errors may be encountered when a resource is created, for instance when you handle the CreateWaitlistEntry method. Examples include, but are not limited to, the following:

  • ABOVE_MAX_PARTY_SIZE is used when the requested waitlist entry is over the merchant’s maximum party size.
  • MERCHANT_CLOSED is used when the waitlist isn't open because the merchant is already closed.

Idempotency

Communication over the network is not always reliable and Google may retry HTTP requests if no response is received. For this reason, all methods that mutate state must be idempotent:

  • CreateWaitlistEntry
  • DeleteWaitlistEntry

For every request message except DeleteWaitlistEntry, idempotency tokens are included to uniquely identify the request. This allows you to distinguish between a retried REST call, with the intent to create a single request, and two separate requests. DeleteWaitlistEntry is uniquely identified by their waitlist entry IDs respectively, so no idempotency token is included in their requests.

The following are some examples of how booking servers handle idempotency:

  • A successful CreateWaitlistEntry HTTP response includes the created waitlist entry ID. If the same CreateWaitlistEntryRequest is received a second time (with the same idempotency_token), then the same CreateWaitlistEntryResponse must be returned. No second waitlist entry is created and no error is returned.

    Note that if a CreateWaitlistEntry attempt fails and the same request is resent, your backend should retry in this case.

The idempotency requirement applies to all methods that mutate state.

Previous
Step 2: Export Feeds
Next
Step 4: End-to-End Testing