Repository files navigation

This repository contains the original interface definitions of publicGoogle APIs that support both REST and gRPC protocols. Reading theoriginal interface definitions can provide a better understanding ofGoogle APIs and help you to utilize them more efficiently. You can alsouse these definitions with open source tools to generate clientlibraries, documentation, and other artifacts.

The recommended way to build the API client libraries is throughBazel >= 4.2.2.

First,install bazel.

To build all libraries:

bazel build //...

To test all libraries:

bazel test //...

To build one library in all languages:

bazel build //google/example/library/v1/...

To build the Java package for one library:

bazel build //google/example/library/v1:google-cloud-example-library-v1-java

Bazel packages exist in all the libraries for Java, Go, Python, Ruby, Node.js, PHP and C#.

Google APIs are typically deployed as API services that are hostedunder different DNS names. One API service may implement multiple APIsand multiple versions of the same API.

Google APIs useProtocol Buffersversion 3 (proto3) as their Interface Definition Language (IDL) todefine the API interface and the structure of the payload messages. Thesame interface definition is used for both REST and RPC versions of theAPI, which can be accessed over different wire protocols.

There are several ways of accessing Google APIs:

1. JSON over HTTP: You can access all Google APIs directly using JSONover HTTP, usingGoogle API client libraryor third-party API client libraries.

2. Protocol Buffers over gRPC: You can access Google APIs publishedin this repository throughGRPC, which isa high-performance binary RPC protocol over HTTP/2. It offers manyuseful features, including request/response multiplex and full-duplexstreaming.

3. Google Cloud Client Libraries:You can use these libraries to access Google Cloud APIs. They are basedon gRPC for better performance and provide idiomatic client surface forbetter developer experience.

This repo contains copies of Google API definitions and related files. Fordiscussions or to raise issues aboutGoogle API client libraries,GRPC orGoogle Cloud Client Libraries pleaserefer to the repos associated with each area.

This repository uses a directory hierarchy that reflects the GoogleAPI product structure. In general, every API has its own rootdirectory, and each major version of the API has its own subdirectory.The proto package names exactly match the directory: this makes iteasy to locate the proto definitions and ensures that the generatedclient libraries have idiomatic namespaces in most programminglanguages. Alongside the API directories live the configuration filesfor theGAPIC toolkit.

NOTE: The major version of an API is used to indicate breakingchange to the API.

To generate gRPC source code for Google APIs in this repository, youfirst need to install both Protocol Buffers and gRPC on your localmachine, then you can runmake LANGUAGE=xxx all to generate thesource code. You need to integrate the generated source code intoyour application build system.

NOTE: The Makefile is only intended to generate source code for theentire repository. It is not for generating linkable client libraryfor a specific API. Please see other repositories underhttps://github.com/googleapis for generating linkable client libraries.

It is difficult to generate Go gRPC source code from this repository,since Go has different directory structure.Please usethis repository instead.