# Step 4: Implement the 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 Standard implementation.** This allows the Actions Center to create appointments, bookings, and reservations with you on behalf of the user. Refer to the [Partner Portal](https://developers.google.com/actions-center/verticals/local-services/e2e/partner-portal/booking-server-endpoint-and-credentials) 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](http://en.wikipedia.org/wiki/Representational_State_Transfer) 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. | Standard implementation | |---| | [Standard service definition](https://developers.google.com/actions-center/verticals/local-services/e2e/reference/booking-server-api-rest/e2e-definitions/proto-interface) Download the proto service definition file. | | Method | HTTP Request | |---|---| | [HealthCheck](https://developers.google.com/actions-center/verticals/local-services/e2e/reference/booking-server-api-rest/e2e-methods/healthcheck-method) | GET /v3/HealthCheck/ | | [BatchAvailabilityLookup](https://developers.google.com/actions-center/verticals/local-services/e2e/reference/booking-server-api-rest/e2e-methods/batchavailabilitylookup-method) | POST /v3/BatchAvailabilityLookup/ | | [CreateBooking](https://developers.google.com/actions-center/verticals/local-services/e2e/reference/booking-server-api-rest/e2e-methods/createbooking-method) | POST /v3/CreateBooking/ | | [UpdateBooking](https://developers.google.com/actions-center/verticals/local-services/e2e/reference/booking-server-api-rest/e2e-methods/updatebooking-method) | POST /v3/UpdateBooking/ | | [GetBookingStatus](https://developers.google.com/actions-center/legacy/reference/booking-server/getbookingstatus-method) | POST /v3/GetBookingStatus/ | | [ListBookings](https://developers.google.com/actions-center/legacy/reference/booking-server/listbookings-method) | POST /v3/ListBookings/ | ### API resources #### Booking The following resource types are used in the standard implementation: - [Slot](https://developers.google.com/actions-center/verticals/local-services/e2e/reference/booking-server-api-rest/e2e-definitions/slot-definition): An inventory slot. - [Booking](https://developers.google.com/actions-center/verticals/local-services/e2e/reference/booking-server-api-rest/e2e-definitions/booking-definition): An appointment for an inventory slot. ### Flow: create a booking This section covers how to create a booking for the standard implementation. ![Figure 1: Workflow to create a booking from a slot](https://developers.google.com/static/actions-center/images/rest_api_v3_booking_flow_1.png) Figure 1: Workflow to create a booking from a slot When a user creates a booking, Google sends you the user's given name, surname, phone number, and email. From your point of view, this booking needs to be treated as a guest checkout, because the Actions Center can't look up the user's account in your system. Make sure the final booking appears identical to your merchants' bookings that come from your booking 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 publicly available SSL/TLS verification tool, such as [Qualys' SSL Server Test](https://www.ssllabs.com/ssltest/). 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](https://partnerdash.google.com/apps/reservewithgoogle/configuration/booking-server). Passwords must be rotated every six months. > [!NOTE] > **Note:** You must set username and password for Sandbox and Production separately by using the [Environment switcher](https://developers.google.com/actions-center/verticals/local-services/e2e/partner-portal/overview/environment-switcher). ### Sample Skeleton Implementations To get started, check out the following sample skeletons of a booking server written for Node.js and Java frameworks: - Node.js skeleton [js-maps-booking-rest-server-v3-skeleton](https://developers.google.com/actions-center/verticals/local-services/e2e/reference/booking-server-code-samples/node-js) - Java skeleton [java-maps-booking-rest-server-v3-skeleton](https://developers.google.com/actions-center/verticals/local-services/e2e/reference/booking-server-code-samples/java) 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** - Return these errors to the client with standard HTTP error codes. See the [full HTTP status code list](https://developers.google.com/actions-center/verticals/local-services/e2e/reference/booking-server-api-rest/e2e-methods/status-codes). - **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 Standard implementation, the possible business logic errors are captured in [Booking Failure](https://developers.google.com/actions-center/verticals/local-services/e2e/reference/booking-server-api-rest/e2e-definitions/bookingfailure-definition) and they're returned in the HTTP response. Business logic errors may be encountered when a resource is created or updated. For instance, when you handle the methods `CreateBooking` or `UpdatingBooking`. Examples include, but aren't limited to, the following: - `SLOT_UNAVAILABLE` is used if the requested slot is no 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 may retry HTTP requests if no response is received. For this reason, all methods that mutate state must be idempotent: - `CreateBooking` - `UpdateBooking` For every request message except `UpdateBooking`, 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. `UpdateBooking` is uniquely identified by their booking 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 ` https://developers.google.com/actions-center/verticals/local-services/e2e/reference/booking-server-api-rest/e2e-methods/createbooking-method` HTTP response includes the created booking. In some cases, payment is processed as part of the booking flow. If the exact same `CreateBookingRequest` is received a second time (with the same `idempotency_token`), then the same `CreateBookingResponse` must be returned. No second booking is created, and the user is charged exactly once, if applicable. Note that if a `CreateBooking` attempt fails and the same request is resent, your backend should retry it in this case. The idempotency requirement applies to all methods that mutate state.