0
# Google API Client for Java
1

2
The Google APIs Client Library for Java is a flexible, efficient, and powerful Java client library for accessing any HTTP-based API on the web, not just Google APIs. It provides OAuth 2.0 authentication, lightweight XML and JSON data models, protocol buffer support, and access to generated libraries for Google APIs.
3

4
## Package Information
5

6
- **Package Name**: google-api-client
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: com.google.api-client
10
- **Artifact ID**: google-api-client
11
- **Installation**: Add to your Maven `pom.xml`:
12

13
```xml
14
<dependency>
15
  <groupId>com.google.api-client</groupId>
16
  <artifactId>google-api-client</artifactId>
17
  <version>2.8.0</version>
18
</dependency>
19
```
20

21
Or to your Gradle `build.gradle`:
22

23
```gradle
24
implementation 'com.google.api-client:google-api-client:2.8.0'
25
```
26

27
## Core Imports
28

29
```java
30
import com.google.api.client.googleapis.services.AbstractGoogleClient;
31
import com.google.api.client.googleapis.services.json.AbstractGoogleJsonClient;
32
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
33
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
34
import com.google.api.client.json.JsonFactory;
35
import com.google.api.client.json.gson.GsonFactory;
36
```
37

38
## Basic Usage
39

40
```java
41
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
42
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
43
import com.google.api.client.json.gson.GsonFactory;
44
import com.google.api.client.http.HttpTransport;
45
import com.google.api.client.json.JsonFactory;
46

47
import java.io.IOException;
48
import java.security.GeneralSecurityException;
49

50
public class GoogleApiExample {
51
    private static final JsonFactory JSON_FACTORY = GsonFactory.getDefaultInstance();
52
    
53
    public static void main(String[] args) throws IOException, GeneralSecurityException {
54
        // Create HTTP transport
55
        HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
56
        
57
        // Load credentials (example with service account)
58
        GoogleCredential credential = GoogleCredential.fromStream(
59
            new FileInputStream("path/to/service-account-key.json"))
60
            .createScoped(Arrays.asList("https://www.googleapis.com/auth/cloud-platform"));
61
        
62
        // Use the transport and credentials with specific Google API clients
63
        // (specific API clients would extend AbstractGoogleJsonClient)
64
    }
65
}
66
```
67

68
## Architecture
69

70
The Google API Client for Java is built around several key architectural components:
71

72
- **HTTP Transport Layer**: Provides HTTP transport implementations (Java.net, Apache HttpClient) with SSL/TLS support and mutual TLS (mTLS) capabilities
73
- **Authentication System**: Complete OAuth 2.0 implementation with support for various credential types (service accounts, user credentials, compute engine credentials)
74
- **Client Framework**: Abstract base classes for building type-safe API clients with JSON and generic data model support
75
- **Media Operations**: Resumable upload and download functionality for large files with progress tracking
76
- **Batch Processing**: Efficient batch request processing to reduce API call overhead
77
- **Error Handling**: Structured JSON error response handling with detailed error information
78
- **Request Management**: Automatic retry logic, request initialization, and parameter validation
79

80
## Capabilities
81

82
### HTTP Transport
83

84
Core HTTP transport implementations with SSL/TLS support and mutual TLS capabilities for secure communication with Google APIs.
85

86
```java { .api }
87
// Java.net transport
88
public static NetHttpTransport newTrustedTransport() 
89
    throws GeneralSecurityException, IOException;
90

91
// Apache HTTP transport  
92
public static ApacheHttpTransport newTrustedTransport()
93
    throws GeneralSecurityException, IOException;
94
```
95

96
[HTTP Transport](./http-transport.md)
97

98
### OAuth2 Authentication
99

100
Complete OAuth 2.0 authentication system supporting various credential types including service accounts, user credentials, and compute engine metadata server authentication.
101

102
```java { .api }
103
public class GoogleCredential extends Credential {
104
    public static GoogleCredential fromStream(InputStream keyStream)
105
        throws IOException;
106
    
107
    public GoogleCredential createScoped(Collection<String> scopes);
108
}
109

110
public class GoogleAuthorizationCodeFlow extends AuthorizationCodeFlow {
111
    public static class Builder extends AuthorizationCodeFlow.Builder {
112
        public GoogleAuthorizationCodeFlow build();
113
    }
114
}
115
```
116

117
[OAuth2 Authentication](./oauth2-auth.md)
118

119
### Client Services  
120

121
Abstract base classes and request handling framework for building type-safe Google API clients with automatic JSON parsing and error handling.
122

123
```java { .api }
124
public abstract class AbstractGoogleClient {
125
    protected AbstractGoogleClient(Builder builder);
126
    public final HttpRequestFactory getRequestFactory();
127
    public final String getApplicationName();
128
}
129

130
public abstract class AbstractGoogleJsonClient extends AbstractGoogleClient {
131
    public final JsonFactory getJsonFactory();
132
    public JsonObjectParser getObjectParser();
133
}
134
```
135

136
[Client Services](./client-services.md)
137

138
### Media Operations
139

140
Resumable upload and download functionality for large files with built-in progress tracking, error recovery, and configurable chunk sizes.
141

142
```java { .api }
143
public final class MediaHttpUploader {
144
    public MediaHttpUploader upload(GenericUrl initiationRequestUrl, HttpContent content);
145
    public void setProgressListener(MediaHttpUploaderProgressListener progressListener);
146
    public void setChunkSize(int chunkSize);
147
}
148

149
public final class MediaHttpDownloader {
150
    public void download(GenericUrl requestUrl, OutputStream outputStream);
151
    public void setProgressListener(MediaHttpDownloaderProgressListener progressListener);
152
}
153
```
154

155
[Media Operations](./media-operations.md)
156

157
### Batch Operations
158

159
Efficient batch request processing to combine multiple API calls into a single HTTP request, reducing network overhead and improving performance.
160

161
```java { .api }
162
public final class BatchRequest {
163
    public BatchRequest queue(HttpRequest request, Class<T> dataClass, 
164
        Class<E> errorClass, BatchCallback<T, E> callback);
165
    public void execute() throws IOException;
166
}
167

168
public interface BatchCallback<T, E> {
169
    void onSuccess(T t, HttpHeaders responseHeaders) throws IOException;
170
    void onFailure(E e, HttpHeaders responseHeaders) throws IOException;
171
}
172
```
173

174
[Batch Operations](./batch-operations.md)
175

176
### JSON Error Handling
177

178
Structured JSON error response parsing and exception handling with detailed error information from Google API responses.
179

180
```java { .api }
181
public class GoogleJsonResponseException extends HttpResponseException {
182
    public GoogleJsonError getDetails();
183
    public static GoogleJsonResponseException from(JsonFactory jsonFactory, 
184
        HttpResponse response);
185
}
186

187
public final class GoogleJsonError extends GenericJson {
188
    public Integer getCode();
189
    public String getMessage();
190
    public List<ErrorInfo> getErrors();
191
}
192
```
193

194
[JSON Error Handling](./json-error-handling.md)
195

196
### Utilities
197

198
Core utility classes providing version information, certificate management, and common functionality used throughout the library.
199

200
```java { .api }
201
public final class GoogleUtils {
202
    public static final String VERSION;
203
    public static final Integer MAJOR_VERSION;
204
    public static final Integer MINOR_VERSION;
205
    public static final Integer BUGFIX_VERSION;
206
    
207
    public static synchronized KeyStore getCertificateTrustStore()
208
        throws IOException, GeneralSecurityException;
209
}
210
```
211

212
[Utilities](./utilities.md)