Setting up a Booking server on your end will allow the Actions Center to create appointments / bookings / reservations with you on behalf of the user.
Implement an API interface based on gRPC
Please note: all new partners should use REST API interface rather than gRPC API.
Implement an API interface based on gRPC. This allows Google to send booking requests. The API surface is defined using gRPC's protobuf based IDL.
We ask our new partners to implement a recommended set of API v2. Partners may select whichever URL and PORT works best for their infrastructure.
This section introduces a recommended set of API v2. It applies to partners who have not implemented API v0. For our current partners that have implemented API v0, please contact the Actions Center to learn more.
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:
Methods
The following API methods are required to be implemented on your end for the gRPC server:
These 5 methods define the required set of BookingService RPCs:
// Manages slot availability, leases and bookings for an inventory of
// appointments
service BookingService {
// Gets availability information for an appointment slot
rpc CheckAvailability(CheckAvailabilityRequest)
returns (CheckAvailabilityResponse) {}
// Creates a booking
rpc CreateBooking(CreateBookingRequest) returns (CreateBookingResponse) {}
// Updates an existing booking
rpc UpdateBooking(UpdateBookingRequest) returns (UpdateBookingResponse) {}
// Gets status for an existing booking
rpc GetBookingStatus(GetBookingStatusRequest)
returns (GetBookingStatusResponse) {}
// Lists all upcoming bookings for a user
rpc ListBookings(ListBookingsRequest) returns (ListBookingsResponse) {}
}
Flow: create a booking
When creating a booking, Google will send the partner the user's given name, surname, phone number, and email. This should be treated as a guest checkout from the partner's point of view as the Actions Center 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.
Skeleton Implementation in Java
To get started, we provide a skeleton gRPC server in Java that can be compiled and installed. Check it out under Samples > gRPC Reference Implementation section. This server has stubbed out gRPC methods that are needed to support the integration, including authentication and health service.
Requirements
gRPC error and business logic error
Two types of errors may occur when a partner backend handles gRPC 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 canonical gRPC error codes. Examples include but are not limited to:
- INVALID_ARGUMENT is used in RPCs such as CheckAvailability and CreateLease, and should be returned if the provided slot contains invalid information.
- NOT_FOUND is used in RPCs such as CreateBooking and ListBookings, and should be returned if the provided identifier is unknown to the partner.
See reference of each method for its canonical gRPC error codes or see the full status code list.
On the contrary, business logic errors should be captured in Booking Failure, and returned in RPC response. Business logic errors may be encountered when creating or updating a resource, i.e., in handling RPCs 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 RPCs if no response is received. For this reason, all RPCs that mutate state (CreateBooking, UpdateBooking) have to be idempotent. Request messages for these RPCs include idempotency tokens to uniquely identify the request and allow the partner to distinguish between a retried RPC (with the intent to create a single booking) and two separate bookings.
Examples include but are not limited to:
- A successful
CreateBooking RPC
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.
gRPC Server security and authentication
Calls from the Actions Center to your backend need to be secured using SSL/TLS with certificate-based, mutual client/server authentication. This requires the use of a valid server certificate for your gRPC implementation and accepting a valid client certificate.
Server certificate: the partner server has to be equipped with a valid server certificate associated with the domain name of the server (refer to this list of accepted root CAs). GRPC server implementations expect to serve a certificate chain that leads up to the root certificate. The easiest way to accomplish this is by appending the intermediate certificate(s) provided by the partner's web host in PEM format to the server certificate (also in PEM format).
The server certificate is verified at connection time and self-signed certificates are not accepted. The actual certificate content is not checked as long as the certificate is valid. You can check the validity of your certificate through the following command:
echo "" | openssl s_client -connect YOUR_URL:YOUR_PORT -showcerts -CApath /etc/ssl/certs
Client certificate: in order to authenticate us (as Google) to the partner, we provide a client certificate issued by the Google Internet Authority G2 (CA certificate) with the following properties:
| Field | Value |
|---|---|
CN |
mapsbooking.businesslink-3.net |
SAN |
DNS:mapsbooking.businesslink-3.net |
Connection attempts without this client certificate should be rejected by the partner server.
To validate the client certificate, the server relies on a set of trusted client root certificates. You can choose to obtain this set of trusted roots from an authority like Mozilla or install the set of roots currently recommended by the Google Internet Authority G2. In both cases, you may have to manually update the root certificates at times.
Implement the gRPC Health Checking Protocol
Implement the GRPC Health Checking
Protocol.
This protocol enables Google to monitor the backend status of your gRPC
implementation. The service
specification
is part of the GRPC distribution. Following the GRPC naming convention, the name
of the service in the health check calls is
ext.maps.booking.partner.v2.BookingService for API v2, or
ext.maps.booking.partner.v0.BookingService for API v0. The health check should
run on the same URL and PORT as the other endpoints.
Other versions
For documentation for other versions of the API, see the following pages: * API v3 * API v0