5.b. Implement Booking server: API v3 (you) - Waitlist-based booking

Setting up a Booking server on your end will allow Reserve with Google to retrieve wait estimates and create waitlist entries with you on behalf of the user.

Implement a REST API interface

Implement an API interface based on REST. This allows Google to send waitlist requests as JSON payloads via HTTP with TLS enabled.

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 Waitlist server:

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

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

Flow: create a waitlist entry

Figure: Create a waitlist entry

When creating a waitlist entry, 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 waitlist entry should be shown to the partner's merchants in their system just like entries that come from the partner's waitlist 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.

For authentication purposes, the partner is going to provide a set of credentials (username and password) and support Basic and Digest authentication methods on their booking server. Credentials need to be rotated periodically and the partner will be contacted by email when a set of credentials is about to expire.

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 for bookings and need to be changed to the required waitlist methods.

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 waitlist entry (see Waitlist Business Logic Failure), e.g., if the requested party size is over the maximum.

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 Waitlist Business Logic Failure, and returned in HTTP response. Business logic errors may be encountered when creating or updating a resource, i.e., in handling method CreateWaitlistEntry. Examples include but are not limited to:

  • 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 is not open because the merchant is already closed.

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 including the ones that mutate state (CreateWaitlistEntry, DeleteWaitlistEntry) must be idempotent. CreateWaitlistEntry includes an idempotency token 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.

Examples include but are not limited to:

  • A successful CreateWaitlistEntry HTTP response includes the created waitlist entry id. If the same CreateWaitlistEntryRequest is received a second time (including idempotency_token), then the same CreateWaitlistEntryResponse has to be returned. No second waitlist entry is created and no error is returned. Note that if a CreateWaitlistEntry attempt fails, the partner backend should retry if the same request is sent again.

Next step

NEXT STEP: Test implementation (both)