Example for Endpoints gRPC backend with HTTP/JSON transcoding. (#1501)

There are enough differences from the pure gRPC example to create
a specific example with transcoding enabled.

Signed-off-by: Christophe Taton <christophe.taton@gmail.com>

endpoints/bookstore-grpc-transcoding/Dockerfile

@@ -0,0 +1,22 @@
+# The Google Cloud Platform Python runtime is based on Debian Jessie
+# You can read more about the runtime at:
+#   https://github.com/GoogleCloudPlatform/python-runtime
+FROM gcr.io/google_appengine/python
+
+# Create a virtualenv for dependencies. This isolates these packages from
+# system-level packages.
+RUN virtualenv -p python3.6 /env
+
+# Setting these environment variables are the same as running
+# source /env/bin/activate.
+ENV VIRTUAL_ENV /env
+ENV PATH /env/bin:$PATH
+
+ADD . /bookstore/
+
+WORKDIR /bookstore
+RUN pip install -r requirements.txt
+
+EXPOSE 8000
+
+ENTRYPOINT ["python", "/bookstore/bookstore_server.py"]

endpoints/bookstore-grpc-transcoding/README.md

@@ -0,0 +1,68 @@
+# Google Cloud Endpoints gRPC with Transcoding Bookstore in Python
+
+[![Open in Cloud Shell][shell_img]][shell_link]
+
+[shell_img]: http://gstatic.com/cloudssh/images/open-btn.png
+[shell_link]: https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/GoogleCloudPlatform/python-docs-samples&page=editor&open_in_editor=endpoints/bookstore-grpc-transcoding/README.md
+
+This example demonstrates how to implement a gRPC server
+with Google Cloud Endpoints and HTTP/JSON Transcoding.
+
+## Installing the dependencies using virtualenv:
+
+    virtualenv bookstore-env
+    source bookstore-env/bin/activate
+
+Install all the Python dependencies:
+
+    pip install -r requirements.txt
+
+Install the [gRPC libraries and tools](http://www.grpc.io/docs/quickstart/python.html#prerequisites)
+
+## Running the Server Locally
+
+To run the server:
+
+    python bookstore_server.py
+
+The `-h` command line flag shows the various settings available.
+
+## Running the Client Locally
+
+To run the client:
+
+    python bookstore_client.py
+
+As with the server, the `-h` command line flag shows the various settings
+available.
+
+## Generating a JWT token from a service account file
+
+To run the script:
+
+    python jwt_token_gen.py --file=account_file --audiences=audiences --issuer=issuer
+
+The output can be used as "--auth_token" for bookstore_client.py
+
+## Regenerating the Protocol Buffer and gRPC API stubs
+
+The bookstore gRPC API is defined by `bookstore.proto`
+The API client stubs and server interfaces are generated by tools.
+
+To make it easier to get something up and running, we've included the generated
+code in the sample distribution.  To modify the sample or create your own gRPC
+API definition, you'll need to update the generated code. To do this, once the
+gRPC libraries and tools are installed, run:
+
+    GOOGLEAPIS=/path/to/googleapis
+    git clone https://github.com/googleapis/googleapis $GOOGLEAPIS
+
+    python -m grpc.tools.protoc \
+        --include_imports \
+        --include_source_info \
+        --proto_path=. \
+        --proto_path=$GOOGLEAPIS \
+        --python_out=. \
+        --grpc_python_out=. \
+        --descriptor_set_out=api_descriptor.pb \
+        bookstore.proto

endpoints/bookstore-grpc-transcoding/api_config.yaml

@@ -0,0 +1,45 @@
+# Copyright 2016 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+#
+# A Bookstore example API configuration.
+#
+# Below, replace MY_PROJECT_ID with your Google Cloud Project ID.
+#
+
+# The configuration schema is defined by service.proto file
+# https://github.com/googleapis/googleapis/blob/master/google/api/service.proto
+type: google.api.Service
+config_version: 3
+
+#
+# Name of the service configuration.
+#
+name: bookstore.endpoints.<MY_PROJECT_ID>.cloud.goog
+
+#
+# API title to appear in the user interface (Google Cloud Console).
+#
+title: Bookstore gRPC API
+apis:
+- name: endpoints.examples.bookstore.Bookstore
+
+#
+# API usage restrictions.
+#
+usage:
+  rules:
+  # ListShelves methods can be called without an API Key.
+  - selector: endpoints.examples.bookstore.Bookstore.ListShelves
+    allow_unregistered_calls: true

endpoints/bookstore-grpc-transcoding/api_config_auth.yaml

@@ -0,0 +1,59 @@
+# Copyright 2016 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+#
+# A Bookstore example API configuration.
+#
+# Below, replace MY_PROJECT_ID with your Google Cloud Project ID.
+#
+
+# The configuration schema is defined by service.proto file
+# https://github.com/googleapis/googleapis/blob/master/google/api/service.proto
+type: google.api.Service
+config_version: 3
+
+#
+# Name of the service configuration.
+#
+name: bookstore.endpoints.<MY_PROJECT_ID>.cloud.goog
+
+#
+# API title to appear in the user interface (Google Cloud Console).
+#
+title: Bookstore gRPC API
+apis:
+- name: endpoints.examples.bookstore.Bookstore
+
+#
+# API usage restrictions.
+#
+usage:
+  rules:
+  - selector: "*"
+    allow_unregistered_calls: true
+
+#
+# Request authentication.
+#
+authentication:
+  providers:
+  - id: google_service_account
+    # Replace SERVICE-ACCOUNT-ID with your service account's email address.
+    issuer: SERVICE-ACCOUNT-ID
+    jwks_uri: https://www.googleapis.com/robot/v1/metadata/x509/SERVICE-ACCOUNT-ID
+  rules:
+  # This auth rule will apply to all methods.
+  - selector: "*"
+    requirements:
+      - provider_id: google_service_account

endpoints/bookstore-grpc-transcoding/bookstore.proto

@@ -0,0 +1,166 @@
+// Copyright 2016 Google Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+////////////////////////////////////////////////////////////////////////////////
+
+syntax = "proto3";
+
+package endpoints.examples.bookstore;
+
+option java_multiple_files = true;
+option java_outer_classname = "BookstoreProto";
+option java_package = "com.google.endpoints.examples.bookstore";
+
+
+import "google/api/annotations.proto";
+import "google/protobuf/empty.proto";
+
+// A simple Bookstore API.
+//
+// The API manages shelves and books resources. Shelves contain books.
+service Bookstore {
+  // Returns a list of all shelves in the bookstore.
+  rpc ListShelves(google.protobuf.Empty) returns (ListShelvesResponse) {
+    // Define HTTP mapping.
+    // Client example (Assuming your service is hosted at the given 'DOMAIN_NAME'):
+    //   curl http://DOMAIN_NAME/v1/shelves
+    option (google.api.http) = { get: "/v1/shelves" };
+  }
+  // Creates a new shelf in the bookstore.
+  rpc CreateShelf(CreateShelfRequest) returns (Shelf) {
+    // Client example:
+    //   curl -d '{"theme":"Music"}' http://DOMAIN_NAME/v1/shelves
+    option (google.api.http) = {
+      post: "/v1/shelves"
+      body: "shelf"
+    };
+  }
+  // Returns a specific bookstore shelf.
+  rpc GetShelf(GetShelfRequest) returns (Shelf) {
+    // Client example - returns the first shelf:
+    //   curl http://DOMAIN_NAME/v1/shelves/1
+    option (google.api.http) = { get: "/v1/shelves/{shelf}" };
+  }
+  // Deletes a shelf, including all books that are stored on the shelf.
+  rpc DeleteShelf(DeleteShelfRequest) returns (google.protobuf.Empty) {
+    // Client example - deletes the second shelf:
+    //   curl -X DELETE http://DOMAIN_NAME/v1/shelves/2
+    option (google.api.http) = { delete: "/v1/shelves/{shelf}" };
+  }
+  // Returns a list of books on a shelf.
+  rpc ListBooks(ListBooksRequest) returns (ListBooksResponse) {
+    // Client example - list the books from the first shelf:
+    //   curl http://DOMAIN_NAME/v1/shelves/1/books
+    option (google.api.http) = { get: "/v1/shelves/{shelf}/books" };
+  }
+  // Creates a new book.
+  rpc CreateBook(CreateBookRequest) returns (Book) {
+    // Client example - create a new book in the first shelf:
+    //   curl -d '{"author":"foo","title":"bar"}' http://DOMAIN_NAME/v1/shelves/1/books
+    option (google.api.http) = {
+      post: "/v1/shelves/{shelf}/books"
+      body: "book"
+    };
+  }
+  // Returns a specific book.
+  rpc GetBook(GetBookRequest) returns (Book) {
+    // Client example - get the first book from the second shelf:
+    //   curl http://DOMAIN_NAME/v1/shelves/2/books/1
+    option (google.api.http) = { get: "/v1/shelves/{shelf}/books/{book}" };
+  }
+  // Deletes a book from a shelf.
+  rpc DeleteBook(DeleteBookRequest) returns (google.protobuf.Empty) {
+    // Client example - delete the first book from the first shelf:
+    //   curl -X DELETE http://DOMAIN_NAME/v1/shelves/1/books/1
+    option (google.api.http) = { delete: "/v1/shelves/{shelf}/books/{book}" };
+  }
+}
+
+// A shelf resource.
+message Shelf {
+  // A unique shelf id.
+  int64 id = 1;
+  // A theme of the shelf (fiction, poetry, etc).
+  string theme = 2;
+}
+
+// A book resource.
+message Book {
+  // A unique book id.
+  int64 id = 1;
+  // An author of the book.
+  string author = 2;
+  // A book title.
+  string title = 3;
+}
+
+// Response to ListShelves call.
+message ListShelvesResponse {
+  // Shelves in the bookstore.
+  repeated Shelf shelves = 1;
+}
+
+// Request message for CreateShelf method.
+message CreateShelfRequest {
+  // The shelf resource to create.
+  Shelf shelf = 1;
+}
+
+// Request message for GetShelf method.
+message GetShelfRequest {
+  // The ID of the shelf resource to retrieve.
+  int64 shelf = 1;
+}
+
+// Request message for DeleteShelf method.
+message DeleteShelfRequest {
+  // The ID of the shelf to delete.
+  int64 shelf = 1;
+}
+
+// Request message for ListBooks method.
+message ListBooksRequest {
+  // ID of the shelf which books to list.
+  int64 shelf = 1;
+}
+
+// Response message to ListBooks method.
+message ListBooksResponse {
+  // The books on the shelf.
+  repeated Book books = 1;
+}
+
+// Request message for CreateBook method.
+message CreateBookRequest {
+  // The ID of the shelf on which to create a book.
+  int64 shelf = 1;
+  // A book resource to create on the shelf.
+  Book book = 2;
+}
+
+// Request message for GetBook method.
+message GetBookRequest {
+  // The ID of the shelf from which to retrieve a book.
+  int64 shelf = 1;
+  // The ID of the book to retrieve.
+  int64 book = 2;
+}
+
+// Request message for DeleteBook method.
+message DeleteBookRequest {
+  // The ID of the shelf from which to delete a book.
+  int64 shelf = 1;
+  // The ID of the book to delete.
+  int64 book = 2;
+}