README.md - maps-booking-v3 - Git at Google

 # Maps Booking

 This repo contains tools and code samples for partners that wish to integrate
 with [Reserve](https://www.google.com/maps/reserve/) API v3.

 ## Testing Client

 Before using the test utilites, the Go programming language must be installed on
 your workstation. A precompiled Go binary for your operating system can be
 [found here](https://golang.org/dl/)

 This guide will assume you're using the default GOPATH and subsequent GOBIN.
 For a comprehensive explanation of the GOPATH env variable please see
 [this document](https://golang.org/dl/) by the Go team.

 ### Installing the utilities with Linux

 First, build your Go directory structure. A comprehensive guide on the intended
 structure of Go code can be [found here.](https://golang.org/doc/code.html)

     mkdir -p $HOME/go/bin $HOME/go/pkg $HOME/go/src/github.com/maps-booking-v3

 Next, add the following to your ~/.bashrc

     export PATH=$PATH:$(go env GOPATH)/bin
     export GOPATH=$(go env GOPATH)
     export GOBIN=$(go env GOPATH)/bin

 Source changes

     source ~/.bashrc

 Remove any files from a previous installation

     rm -rf $HOME/go/src/github.com/maps-booking-v3/

 Next, retrieve the utilities from the
 [maps-booking-v3 repository](https://maps-booking.googlesource.com/)

     git clone https://maps-booking.googlesource.com/maps-booking-v3 $HOME/go/src/github.com/maps-booking-v3/

 Download all dependencies

     cd $HOME/go
     go get -d ./...

 If installing the order based test client, run

     go install $HOME/go/src/github.com/maps-booking-v3/testclient/orderClient.go

 Or the booking based test client, run

     go install $HOME/go/src/github.com/maps-booking-v3/testclient/bookingClient.go

 Or the waitlist based test client, run

     go install $HOME/go/src/github.com/maps-booking-v3/testclient/waitlistClient.go

 ### Installing the utilities with Windows Powershell

 First, build your Go directory structure. A comprehensive guide on the intended
 structure of Go code can be [found here.](https://golang.org/doc/code.html)

     $env:HOME = $env:USERPROFILE
     md $env:HOME\go\bin
     md $env:HOME\go\pkg
     md $env:HOME\go\src\github.com\maps-booking-v3

 Next, set the appropriate environment variables

     $env:PATH = $env:PATH + ";" + (go env GOPATH) + "\bin"
     $env:GOPATH = (go env GOPATH)
     $env:GOBIN = (go env GOPATH) + "\bin"

 Remove any files from a previous installation

     rd -r $env:HOME\go\src\github.com\maps-booking-v3\

 Next, retrieve the utilities from the
 [maps-booking-v3 repository](https://maps-booking.googlesource.com/)

     git clone https://maps-booking.googlesource.com/maps-booking-v3 $env:HOME\go\src\github.com\maps-booking-v3\

 Download all dependencies

     cd $env:HOME\go
     # NOTE: You may see output '...cannot find package...' when running the following 'go get' command.
     # These are likely just warnings and you can proceed with the installation.
     go get -d .\...

 If installing the order based test client, run

     go install $env:HOME\go\src\github.com\maps-booking-v3\testclient\orderClient.go

 Or the booking based test client, run

     go install $env:HOME\go\src\github.com\maps-booking-v3\testclient\bookingClient.go

 Or the waitlist based test client, run

     go install $env:HOME\go\src\github.com\maps-booking-v3\testclient\waitlistClient.go

 ### Using the utilities

 After following the install steps above an executable should now live under the
 path

     $HOME/go/bin/

 or

     $env:HOME\go\bin\

 All available flags can be displayed using the '--help' flag. The currently
 accepted flags are:

     bookingClient.go
     -all_tests
         Whether to test all endpoints.
     -availability_feed string
         Absolute path to availability feed required for all tests except health.
         Feeds can be in either json or pb3 format
     -booking_status_test
         Whether to test the GetBookingStatus endpoint.
     -booking_test
         Whether to test the CreateBooking endpoint.
     -cancel_all_bookings
         This option assumes that the ListBookings and UpdateBooking endpoints
         are fully functional. This is a convenience flag for purging your system
         of all previously created bookings.
     -check_availability_test
         Whether to test the CheckAvailability endpoint.
     -health_check_test
         Whether to test the Health endpoint.
     -list_bookings_test
         Whether to test the ListBookings endpoint
     -num_test_slots int
         Maximum number of slots to test from availability_feed. Slots will be
         selected randomly (default 10)
     -output_dir string
         Absolute path of dir to dump log file.
     -rescheduling_test
         Whether to test the UpdateBooking endpoint.
     -server_addr string
         Your http server's address in the format of host:port
         (default "localhost:443")
     -credentials_file string
         File containing credentials for your server. Leave blank to bypass authentication.
         File should have exactly one line of the form 'username:password'.
     -ca_file string
         Absolute path to your server's Certificate Authority root cert.
         Downloading all roots currently recommended by the Google Internet
         Authority is a suitable alternative https://pki.google.com/roots.pem.
         Leave blank to connect using http rather than https.
     -full_server_name string
         Fully qualified domain name. Same name used to sign CN. Only necessary if ca_file is specified and the base URL differs from the server address.
     -output_to_terminal bool
         Output to terminal rather than a file.
     -use_batch_availability_lookup bool
         Whether to use the BatchAvailabilityLookup RPC (as opposed to the deprecated CheckAvailability)

     orderClient.go
     -all_tests
         Whether to test all endpoints syncronously, including ListOrders flow.
     -availability_feed string
         Absolute path to availability feed required for all tests except health. Feeds can be in either json or pb3 format
     -ca_file string
         Absolute path to your server's Certificate Authority root cert. Downloading all roots currently recommended by the Google Internet Authority is a suitable alternative https://pki.google.com/roots.pem. Leave blank to connect using http rather than https.
     -check_order_test
         Whether to test the CheckOrderFulfillability endpoint.
     -create_order_test
         Whether to test the CreateOrder endpoint.
     -credentials_file string
         File containing credentials for your server. Leave blank to bypass authentication. File should have exactly one line of the form 'username:password'.
     -full_server_name string
         Fully qualified domain name. Same name used to sign CN. Only necessary if ca_file is specified and the base URL differs from the server address.
     -health_check_test
         Whether to test the Health endpoint.
     -num_test_slots int
         Maximum number of slots to test from availability_feed. Slots will be selected randomly (default 10)
     -output_dir string
         Absolute path of dir to dump log file.
     -server_addr string
         Your http server's address in the format of host:port (default "example.com:80")
     -service_feed string
         Absolute path to service feed required for all tests except health. Feeds can be in either json or pb3 format
     -output_to_terminal bool
         Output to terminal rather than a file.

     waitlistClient.go
     -server_addr string
         Your http server's address in the format of host:port (default "example.com:80")
     -service_feed string
         Absolute path to service feed required for all tests except health. Feeds can be in either json or pb3 format.
     -all_tests
         Whether to test all endpoints syncronously.
     -health_check_test
         Whether to test the Health endpoint.
     -batch_get_wait_estimates_test
         Whether to test the BatchGetWaitEstimates endpoint.
     -create_waitlist_entry_test
         Whether to test the CreateWaitlistEntry endpoint.
     -get_waitlist_entry_test
         Whether to test the GetWaitlistEntry endpoint.
     -delete_waitlist_entry_test
         Whether to test the DeleteWaitlistEntry endpoint.
     -ca_file string
         Absolute path to your server's Certificate Authority root cert. Downloading all roots currently recommended by the Google Internet Authority is a suitable alternative https://pki.google.com/roots.pem. Leave blank to connect using http rather than https.
     -credentials_file string
         File containing credentials for your server. Leave blank to bypass authentication. File should have exactly one line of the form 'username:password'.
     -full_server_name string
         Fully qualified domain name. Same name used to sign CN. Only necessary if ca_file is specified and the base URL differs from the server address.
     -num_test_services int
         Maximum number of services to test from service_feed. Services will be selected randomly (default 10)
     -output_dir string
         Absolute path of dir to dump log file.
     -output_to_terminal bool
         Output to terminal rather than a file.

 Plese note that this testing tool makes reservations as a test user with
 **user_id = 0**. Therefore, if you are running the tool many times, or before
 final tests, you might want cancel all previous bookings for that user to make
 sure all existing bookings for the user are deleted:

     bin/bookingClient -server_addr="localhost:443" -cancel_all_bookings=true -output_dir="/tmp"

 Example Usage:

     bin/bookingClient -server_addr="localhost:443" -check_availability_test=true -output_dir="/tmp" -availability_feed="/tmp/test.json"

     bin/orderClient -server_addr="external-dns:443" -all_tests=true -output_dir="/tmp" -availability_feed="/tmp/test.json" -service_feed="/tmp/service.json"

     bin/waitlistClient -server_addr="external-dns:443" -all_tests=true -output_dir="/tmp" service_feed="/tmp/service.json"

 ### Testing

 It is important that as part of testing you verify all aspects of the server
 invocation - authentication, availability, cancellation, and rescheduling tests.
 As the final step, you must be able to execute the designated utility with the
 flag -all_tests=true and it should successfully pass the entire series of tests.

 ### Parsing the output

 The test utilities will output a file with the prefix 'http_test_client_log_'
 followed by a timestamp in RFC3339 format. The output file contains a complete
 log of all Requests and Responses sent/received by the testing tool as well as
 diffs of the expected response in the event of errors. Similar to a compiler, an
 overview of the entire run can be found at the end of the file for user friendly
 digestion.
	# Maps Booking

	This repo contains tools and code samples for partners that wish to integrate
	with [Reserve](https://www.google.com/maps/reserve/) API v3.

	## Testing Client

	Before using the test utilites, the Go programming language must be installed on
	your workstation. A precompiled Go binary for your operating system can be
	[found here](https://golang.org/dl/)

	This guide will assume you're using the default GOPATH and subsequent GOBIN.
	For a comprehensive explanation of the GOPATH env variable please see
	[this document](https://golang.org/dl/) by the Go team.

	### Installing the utilities with Linux

	First, build your Go directory structure. A comprehensive guide on the intended
	structure of Go code can be [found here.](https://golang.org/doc/code.html)

	mkdir -p $HOME/go/bin $HOME/go/pkg $HOME/go/src/github.com/maps-booking-v3

	Next, add the following to your ~/.bashrc

	export PATH=$PATH:$(go env GOPATH)/bin
	export GOPATH=$(go env GOPATH)
	export GOBIN=$(go env GOPATH)/bin

	Source changes

	source ~/.bashrc

	Remove any files from a previous installation

	rm -rf $HOME/go/src/github.com/maps-booking-v3/

	Next, retrieve the utilities from the
	[maps-booking-v3 repository](https://maps-booking.googlesource.com/)

	git clone https://maps-booking.googlesource.com/maps-booking-v3 $HOME/go/src/github.com/maps-booking-v3/

	Download all dependencies

	cd $HOME/go
	go get -d ./...

	If installing the order based test client, run

	go install $HOME/go/src/github.com/maps-booking-v3/testclient/orderClient.go

	Or the booking based test client, run

	go install $HOME/go/src/github.com/maps-booking-v3/testclient/bookingClient.go

	Or the waitlist based test client, run

	go install $HOME/go/src/github.com/maps-booking-v3/testclient/waitlistClient.go

	### Installing the utilities with Windows Powershell

	First, build your Go directory structure. A comprehensive guide on the intended
	structure of Go code can be [found here.](https://golang.org/doc/code.html)

	$env:HOME = $env:USERPROFILE
	md $env:HOME\go\bin
	md $env:HOME\go\pkg
	md $env:HOME\go\src\github.com\maps-booking-v3

	Next, set the appropriate environment variables

	$env:PATH = $env:PATH + ";" + (go env GOPATH) + "\bin"
	$env:GOPATH = (go env GOPATH)
	$env:GOBIN = (go env GOPATH) + "\bin"

	Remove any files from a previous installation

	rd -r $env:HOME\go\src\github.com\maps-booking-v3\

	Next, retrieve the utilities from the
	[maps-booking-v3 repository](https://maps-booking.googlesource.com/)

	git clone https://maps-booking.googlesource.com/maps-booking-v3 $env:HOME\go\src\github.com\maps-booking-v3\

	Download all dependencies

	cd $env:HOME\go
	# NOTE: You may see output '...cannot find package...' when running the following 'go get' command.
	# These are likely just warnings and you can proceed with the installation.
	go get -d .\...

	If installing the order based test client, run

	go install $env:HOME\go\src\github.com\maps-booking-v3\testclient\orderClient.go

	Or the booking based test client, run

	go install $env:HOME\go\src\github.com\maps-booking-v3\testclient\bookingClient.go

	Or the waitlist based test client, run

	go install $env:HOME\go\src\github.com\maps-booking-v3\testclient\waitlistClient.go

	### Using the utilities

	After following the install steps above an executable should now live under the
	path

	$HOME/go/bin/

	or

	$env:HOME\go\bin\

	All available flags can be displayed using the '--help' flag. The currently
	accepted flags are:

	bookingClient.go
	-all_tests
	Whether to test all endpoints.
	-availability_feed string
	Absolute path to availability feed required for all tests except health.
	Feeds can be in either json or pb3 format
	-booking_status_test
	Whether to test the GetBookingStatus endpoint.
	-booking_test
	Whether to test the CreateBooking endpoint.
	-cancel_all_bookings
	This option assumes that the ListBookings and UpdateBooking endpoints
	are fully functional. This is a convenience flag for purging your system
	of all previously created bookings.
	-check_availability_test
	Whether to test the CheckAvailability endpoint.
	-health_check_test
	Whether to test the Health endpoint.
	-list_bookings_test
	Whether to test the ListBookings endpoint
	-num_test_slots int
	Maximum number of slots to test from availability_feed. Slots will be
	selected randomly (default 10)
	-output_dir string
	Absolute path of dir to dump log file.
	-rescheduling_test
	Whether to test the UpdateBooking endpoint.
	-server_addr string
	Your http server's address in the format of host:port
	(default "localhost:443")
	-credentials_file string
	File containing credentials for your server. Leave blank to bypass authentication.
	File should have exactly one line of the form 'username:password'.
	-ca_file string
	Absolute path to your server's Certificate Authority root cert.
	Downloading all roots currently recommended by the Google Internet
	Authority is a suitable alternative https://pki.google.com/roots.pem.
	Leave blank to connect using http rather than https.
	-full_server_name string
	Fully qualified domain name. Same name used to sign CN. Only necessary if ca_file is specified and the base URL differs from the server address.
	-output_to_terminal bool
	Output to terminal rather than a file.
	-use_batch_availability_lookup bool
	Whether to use the BatchAvailabilityLookup RPC (as opposed to the deprecated CheckAvailability)

	orderClient.go
	-all_tests
	Whether to test all endpoints syncronously, including ListOrders flow.
	-availability_feed string
	Absolute path to availability feed required for all tests except health. Feeds can be in either json or pb3 format
	-ca_file string
	Absolute path to your server's Certificate Authority root cert. Downloading all roots currently recommended by the Google Internet Authority is a suitable alternative https://pki.google.com/roots.pem. Leave blank to connect using http rather than https.
	-check_order_test
	Whether to test the CheckOrderFulfillability endpoint.
	-create_order_test
	Whether to test the CreateOrder endpoint.
	-credentials_file string
	File containing credentials for your server. Leave blank to bypass authentication. File should have exactly one line of the form 'username:password'.
	-full_server_name string
	Fully qualified domain name. Same name used to sign CN. Only necessary if ca_file is specified and the base URL differs from the server address.
	-health_check_test
	Whether to test the Health endpoint.
	-num_test_slots int
	Maximum number of slots to test from availability_feed. Slots will be selected randomly (default 10)
	-output_dir string
	Absolute path of dir to dump log file.
	-server_addr string
	Your http server's address in the format of host:port (default "example.com:80")
	-service_feed string
	Absolute path to service feed required for all tests except health. Feeds can be in either json or pb3 format
	-output_to_terminal bool
	Output to terminal rather than a file.

	waitlistClient.go
	-server_addr string
	Your http server's address in the format of host:port (default "example.com:80")
	-service_feed string
	Absolute path to service feed required for all tests except health. Feeds can be in either json or pb3 format.
	-all_tests
	Whether to test all endpoints syncronously.
	-health_check_test
	Whether to test the Health endpoint.
	-batch_get_wait_estimates_test
	Whether to test the BatchGetWaitEstimates endpoint.
	-create_waitlist_entry_test
	Whether to test the CreateWaitlistEntry endpoint.
	-get_waitlist_entry_test
	Whether to test the GetWaitlistEntry endpoint.
	-delete_waitlist_entry_test
	Whether to test the DeleteWaitlistEntry endpoint.
	-ca_file string
	Absolute path to your server's Certificate Authority root cert. Downloading all roots currently recommended by the Google Internet Authority is a suitable alternative https://pki.google.com/roots.pem. Leave blank to connect using http rather than https.
	-credentials_file string
	File containing credentials for your server. Leave blank to bypass authentication. File should have exactly one line of the form 'username:password'.
	-full_server_name string
	Fully qualified domain name. Same name used to sign CN. Only necessary if ca_file is specified and the base URL differs from the server address.
	-num_test_services int
	Maximum number of services to test from service_feed. Services will be selected randomly (default 10)
	-output_dir string
	Absolute path of dir to dump log file.
	-output_to_terminal bool
	Output to terminal rather than a file.

	Plese note that this testing tool makes reservations as a test user with
	user_id = 0. Therefore, if you are running the tool many times, or before
	final tests, you might want cancel all previous bookings for that user to make
	sure all existing bookings for the user are deleted:

	bin/bookingClient -server_addr="localhost:443" -cancel_all_bookings=true -output_dir="/tmp"

	Example Usage:

	bin/bookingClient -server_addr="localhost:443" -check_availability_test=true -output_dir="/tmp" -availability_feed="/tmp/test.json"

	bin/orderClient -server_addr="external-dns:443" -all_tests=true -output_dir="/tmp" -availability_feed="/tmp/test.json" -service_feed="/tmp/service.json"

	bin/waitlistClient -server_addr="external-dns:443" -all_tests=true -output_dir="/tmp" service_feed="/tmp/service.json"

	### Testing

	It is important that as part of testing you verify all aspects of the server
	invocation - authentication, availability, cancellation, and rescheduling tests.
	As the final step, you must be able to execute the designated utility with the
	flag -all_tests=true and it should successfully pass the entire series of tests.

	### Parsing the output

	The test utilities will output a file with the prefix 'http_test_client_log_'
	followed by a timestamp in RFC3339 format. The output file contains a complete
	log of all Requests and Responses sent/received by the testing tool as well as
	diffs of the expected response in the event of errors. Similar to a compiler, an
	overview of the entire run can be found at the end of the file for user friendly
	digestion.