For many developers, the easiest way to call a Google API is with one of our client libraries. But occasionally someone may prefer to make API calls directly - perhaps from a language or environment that we don’t support or using a different networking library or tool. Here we’ll show you how to do it.
This page focuses on calling Google APIs directly using their underlying RPC interfaces. Most Google APIs are also available as REST services. For that, see How to Call Google APIs, REST Edition.
Most Google APIs are designed as RPC APIs using Protocol Buffers. The Protocol Buffers definitions of public Google APIs are hosted on GitHub in the googleapis/googleapis repository.
For these examples, we’ll use the Cloud Natural Language API, which is defined by google/cloud/language/v1/language_service.proto. The RPC details are documented online in the Google Cloud Natural Language API reference. We’ll call the AnalyzeEntities API, which takes a block of text as input and returns a list of names and nouns that it finds in the text along with some interesting properties of each entity.
For all Google RPC APIs, the messages that are sent and received using the Protocol Buffers encoding, and the definitive descriptions of these APIs are written in the Protocol Buffers Language.
To compile Protocol Buffer Language files, you’ll need protoc, the Protocol
Buffer compiler. You can download protoc from the
google/protobuf release page on
GitHub (look for the protoc release for your machine architecture, e.g.
protoc-3.6.0-linux-x86_64.zip) or build it from source (this will take a
while).
You’ll probably also need a code generation plugin for the language that you’re using. Plugins are standalone executables written in many different languages, and the plugin interface is defined in the plugin.proto file. Here are some plugins that we have used:
For a list of Google-supported languages, see the Protocol Buffers API Reference.
gRPC is the recommended way to call Google RPC APIs. gRPC
support is typically provided by additional protoc plugins that generate code
for API clients and servers. This code uses lower-level primitives that send
messages using gRPC’s HTTP/2-based messaging system, which supports request
multiplexing, streaming APIs, and advanced flow control. To learn more about
working with gRPC, visit grpc.io/docs.
If gRPC support is unavailable, Google APIs can also be called using HTTP/1.1 or later using the fallback protocol described in the next section.
To use Google APIs, a client needs to authenticate with an API key or an OAuth token. For more information, see the Google Cloud Authentication Overview.
API keys can be obtained from the Google Cloud Console > Credentials page. OAuth tokens can be obtained by OAuth 2 clients and libraries. For a sample command-line client, see the oauth2l on GitHub.
Along with gRPC, most Google APIs support a simple fallback protocol that uses Protocol Buffers (protobuf) over HTTP. It allows clients to call Google APIs directly, often using standard library functions.
This protocol uses fixed URLs to specify the RPC endpoints, and passes request/response messages as HTTP request/response body using HTTP POST. It uses normal HTTP headers to pass the RPC metadata, such as System Parameters.
RPC URLs have the following format:
URL ::= BaseUrl "/" Service "/" Method
BaseUrl. This is the base URL published by service owners, either via
documentation or service discovery. For most Google APIs, the BaseUrl looks
like https://language.googleapis.com/$rpc (experimental: this format may
change in the future). The base address can be found in the API reference
documentation where it is identified as the Service name. For this example,
language.googleapis.com is found in the Google Cloud Natural Language API
Reference.
Service. This is the fully qualified protobuf service name, such as
google.cloud.language.v1.LanguageService. In this case,
google.cloud.language.v1 is the package name in
google/cloud/language/v1/language_service.proto and LanguageService is
the name of the service section found in this file.
Method. This is the protobuf rpc name, such as AnnotateText.
RPC request messages are serialized and sent as the HTTP request body. For the server to handle the request properly, the client must set several HTTP request headers:
Content-Type. The request message format is specified by the Content-Type
header and must be application/x-protobuf.
X-Goog-Api-Key. This specifies a valid Google API key. It is optional if the Authorization header is used.
Authorization. This specifies a valid Google OAuth access token in the
format of Bearer {token}. It is optional if an API key is provided.
For successful requests, the HTTP status code is 200 and the HTTP response
body contains the serialized RPC response message. For unsuccessful requests,
the HTTP status code is the HTTP mapping for
google.rpc.Code
and the HTTP response body contains a serialized
google.rpc.Status
message. For details, see Errors
in the API Design Guide.
The HTTP response contains at least the following headers:
application/x-protobuf.
Different values can be returned for network errors, such as when a message
is rejected by a network proxy. All such errors will be accompanied by
appropriate HTTP status codes.To illustrate how easily the gRPC fallback protocol can be used to call Google RPC APIs, we’ve written a few examples. Each is as basic as possible - using standard library functions wherever possible and commonly-used Protocol Buffer support code. If you write one in a different language, send us a pull request!