Did you ever heard about gRPC, many of the Cloud APIs are gRPC-enabled, which means not just REST, they also expose an RPC interface. And if you know gRPC, it provides us a performance for our application over REST.

Just like most cloud platforms, Google Cloud Platform (GCP) provides APIs, which called Cloud APIs to interact with its services. All Cloud APIs expose a REST interface, which you can either call directly with any HTTP client or use GCP provided client libraries. REST APIs, that seems enough for us, right? But hold on, did you ever heard about gRPC, many of the Cloud APIs are gRPC-enabled, which means not just REST, they also expose an RPC interface. And if you know gRPC, it provides us performance for our application over REST.

In this article, we will walk through step by step on how to call Google Cloud APIs directly using their underlying RPC interfaces with 2 different methods. First, we will use the standard gRPC client. And then we will use gRPC fallback, a mechanism introduced exclusively on GCP. The reason why I write this article is that I had a hard time struggling with Google’s document and the gRPC fallback is a really interesting feature. Hope this will help you save your time when using the Google Cloud APIs via RPC.

gRPC recap

Before jumping into how to use these gRPC-enabled APIs, if you have not known what gRPC is and why it gives better performance over REST, please follow these posts to have a quick overview:

gRPC is proven to be 10 times faster than REST, this is why we want to use gRPC over REST.

Standard gRPC client

In this part, we will use the standard gRPC client with the stubs and services generate form protobuf files.

Step 1: Authentication

We need to authenticate our request in order to use GCP’s APIs (For more information, see: Google Cloud Authentication Overview). In this section, we will use service account to authenticate. We can create a service account on Google Cloud Console > Service Accounts page:

Grant our service account the Project Viewer role:

Finally, create a service account key:

Store the json key file as “service-account.json”, we will use it later.

Step 2: Getting the Protocol Buffers definition

To generate the client code for an API, first, we need the Protocol Buffers (protobuf) definition of that API, which are hosted in the googleapis/googleapis repository on GitHub.

In the example, we  will use the Cloud Billing Catalog API, which is designed by cloud/billing/v1/cloud_catalog.proto. We will call the ListSkus API, which receive cloud service id as input and returns all publicly available SKUs for a given GCP’s cloud service.

Step 3: Generating the client code

Follow Quickstart and we will have the cloud_catalog.pb.go and cloud_catalog_grpc.pb.go files.

You wiil need some dependencies from the googleapis/googleapis reposistory . If you have no prior experince with gRPC, just clone the whole reposistory, then run protoc command on the local directory.

Step 4: Making request

And we have the response:

gRPC Fallback

This is a quite interesting feature of Cloud APIs, they support another way to use gRPC, a simple fallback protocol that uses protobuf over HTTP, which you can use any standard HTTP client to call. Just a simple HTTP POST request and GCP will take care of the rest.

Step 1: Authentication

Like the previous section, we need to authenticate our request. This time, we will use API key to authenticate.

We can create a service account on Google Cloud Console > Credentials page:

Step 2: Constructing the URL

Here is the format of a RPC URL:

{BASE_URL} /{SERVICE} / {METHOD}

  • BASE_URL: base URL published by service owners, ends with “/$grpc”
  • SERVICE: fully quilified protobuf service name (PACKAGE_NAME + SERVICE_NAME)
  • METHOD: the protobuf RPC name

For example, the Cloud Billing Catalog API have the RPC URL:

cloudbilling.googleapis.com/$rpc/google.cloud.billing.v1.CloudCatalog/ListSkus

In which we have:

  • BASE_URL: cloudbilling.googleapis.com/$rpc
  • SERVICE: google.cloud.billing.v1.CloudCatalog
  • METHOD: ListSkus

We can easily find these element in the protobuf definition:

Step 3: Making request

Our request must includes following headers:

  • Content-Type: application/x-protobuf

This header is needed to trigger the gRPC Fallback

  • X-Google-Api-key: authentication header, in case we use API key for authentication
  • Authorization: authentication header, in case we use OAuth2 for authenticaiton

Now, let make a request:

In the example, the request body is serialized RPC request message:

Then simply put the serialized data into the body of a normal HTTP POST request:

If the request is successful, it will return HTTP status code 200. The response body contains the serialize RPC response message and we must deserialize it with:

And we have the response with HTTP status code 200:

In case of unsuccessful, we will recevive HTTP status code match the mapping in google.rpc.Code and the response body contains a serialized google.rpc.Status (See Erros for more information).

For example, we will leave the API key empty and get the response with HTTP status code 403:

Conclusion

Reaching the final of this article, I hope now you can call GCP’s APIs via RPC with ease. With the proven performance of RPC over REST, I think in the near future, not just GCP, most of the cloud platforms will expose their APIs with RPC interface too and we will have articles on theirs APIs as well.

Le Minh Man – Solution & Technology Unit, FPT Software

Credits:

Related posts: