1# Google APIs
2
3This repository contains the original interface definitions of public
4Google APIs that support both REST and gRPC protocols. Reading the
5original interface definitions can provide a better understanding of
6Google APIs and help you to utilize them more efficiently. You can also
7use these definitions with open source tools to generate client
8libraries, documentation, and other artifacts.
9
10## Building
11### Bazel
12
13The recommended way to build the API client libraries is through
14[Bazel](https://bazel.build/) >= 2.0.0.
15
16First, [install bazel](https://docs.bazel.build/versions/master/install.html).
17
18To build all libraries:
19
20```
21bazel build //...
22```
23
24To test all libraries:
25
26```
27bazel test //...
28```
29
30To build one library in all languages:
31
32```
33bazel build //google/example/library/v1/...
34```
35
36To build the Java package for one library:
37
38```
39bazel build //google/example/library/v1:google-cloud-library-v1-java
40```
41
42Bazel packages exist in all the libraries for Java, Go, Python, Ruby, Node.js, PHP and C#.
43
44## Overview
45
46Google APIs are typically deployed as API services that are hosted
47under different DNS names. One API service may implement multiple APIs
48and multiple versions of the same API.
49
50Google APIs use [Protocol Buffers](https://github.com/google/protobuf)
51version 3 (proto3) as their Interface Definition Language (IDL) to
52define the API interface and the structure of the payload messages. The
53same interface definition is used for both REST and RPC versions of the
54API, which can be accessed over different wire protocols.
55
56There are several ways of accessing Google APIs:
57
581.  JSON over HTTP: You can access all Google APIs directly using JSON
59over HTTP, using
60[Google API client library](https://developers.google.com/api-client-library)
61or third-party API client libraries.
62
632.  Protocol Buffers over gRPC: You can access Google APIs published
64in this repository through [GRPC](https://github.com/grpc), which is
65a high-performance binary RPC protocol over HTTP/2. It offers many
66useful features, including request/response multiplex and full-duplex
67streaming.
68
693.  [Google Cloud Client Libraries](https://cloud.google.com/apis/docs/cloud-client-libraries):
70You can use these libraries to access Google Cloud APIs. They are based
71on gRPC for better performance and provide idiomatic client surface for
72better developer experience.
73
74## Discussions
75
76This repo contains copies of Google API definitions and related files.  For
77discussions or to raise issues about
78[Google API client libraries](https://github.com/googleapis),
79[GRPC](https://github.com/grpc) or
80[Google Cloud Client Libraries](https://github.com/googlecloudplatform) please
81refer to the repos associated with each area.
82
83## Repository Structure
84
85This repository uses a directory hierarchy that reflects the Google
86API product structure. In general, every API has its own root
87directory, and each major version of the API has its own subdirectory.
88The proto package names exactly match the directory: this makes it
89easy to locate the proto definitions and ensures that the generated
90client libraries have idiomatic namespaces in most programming
91languages. Alongside the API directories live the configuration files
92for the [GAPIC toolkit](https://github.com/googleapis/toolkit).
93
94**NOTE:** The major version of an API is used to indicate breaking
95change to the API.
96
97## Generate gRPC Source Code
98
99To generate gRPC source code for Google APIs in this repository, you
100first need to install both Protocol Buffers and gRPC on your local
101machine, then you can run `make LANGUAGE=xxx all` to generate the
102source code. You need to integrate the generated source code into
103your application build system.
104
105**NOTE:** The Makefile is only intended to generate source code for the
106entire repository. It is not for generating linkable client library
107for a specific API. Please see other repositories under
108https://github.com/googleapis for generating linkable client libraries.
109
110### Go gRPC Source Code
111It is difficult to generate Go gRPC source code from this repository,
112since Go has different directory structure.
113Please use [this repository](https://github.com/google/go-genproto) instead.
114