> [!NOTE]
> **Note:** This page describes how to implement the booking server with API v2. See [Implement the booking server](https://developers.google.com/actions-center/verticals?vertical_redirect_fragment=guides/end-to-end-integration/implement-booking-server) for instructions to use with the latest version.

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](http://www.grpc.io/). This allows Google to send booking requests. The API surface
is defined using [gRPC's protobuf based
IDL](http://www.grpc.io/docs/guides/concepts.html#service-definition).

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](https://developers.google.com/static/actions-center/download/apitemplate.v2.booking_service.proto)

### API resources

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

- [Slot](https://developers.google.com/actions-center/reference/grpc-api-v2/slot-specification): an inventory slot
- [Booking](https://developers.google.com/actions-center/reference/grpc-api-v2/booking-specification): appointment for an inventory slot

## Methods

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

- [CheckAvailability](https://developers.google.com/actions-center/reference/grpc-api-v2/checkavailability-method)
- [CreateBooking](https://developers.google.com/actions-center/reference/grpc-api-v2/createbooking-method)
- [UpdateBooking](https://developers.google.com/actions-center/reference/grpc-api-v2/updatebooking-method)
- [GetBookingStatus](https://developers.google.com/actions-center/reference/grpc-api-v2/getbookingstatus-method)
- [ListBookings](https://developers.google.com/actions-center/reference/grpc-api-v2/listbookings-method)

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

![](https://developers.google.com/static/actions-center/images/grpc_api_v2_booking_flow_1.png) **Figure 1:** 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. 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](https://developers.google.com/actions-center/legacy/booking-server-code-samples/gRPC-v2/java.grpc-server)
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](https://developers.google.com/actions-center/reference/grpc-api-v2/booking-failure-specification)),
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](https://developers.google.com/actions-center/reference/grpc-api-v2/status_codes).

On the contrary, business logic errors should be captured in [Booking
Failure](https://developers.google.com/actions-center/reference/grpc-api-v2/booking-failure-specification), 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](https://developers.google.com/actions-center/reference/grpc-api-v2/createbooking-method) 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](https://wiki.mozilla.org/CA:IncludedCAs)).
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

> [!NOTE]
> **Note:** Certificates have an expiration date. It is the partner's responsibility to be sure their certificate gets updated before it expires to avoid any service outage with the Actions Center.

**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](https://pki.google.com/GIAG2.crt)) 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](https://wiki.mozilla.org/CA:IncludedCAs)
or install the [set of roots currently recommended by the Google Internet
Authority G2](https://pki.google.com/roots.pem). 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](https://github.com/grpc/grpc/blob/master/doc/health-checking.md).
This protocol enables Google to monitor the backend status of your gRPC
implementation. The [service
specification](https://github.com/grpc/grpc/blob/master/src/proto/grpc/health/v1/health.proto)
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.

> [!NOTE]
> **Note:** Check out the reference implementations in [Ruby](https://developers.google.com/actions-center/legacy/booking-server-code-samples/gRPC-v0-legacy/partner-api-ruby).

## Other versions

For documentation for other versions of the API, see the following pages:
\* [API v3](https://developers.google.com/actions-center/verticals?vertical_redirect_fragment=guides/end-to-end-integration/implement-booking-server)
\* [API v0](https://developers.google.com/actions-center/legacy/archived-guides/implement-booking-server-v0)