cure-google-api-client 0.8.7.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (62) hide show
  1. checksums.yaml +7 -0
  2. data/CHANGELOG.md +178 -0
  3. data/Gemfile +9 -0
  4. data/LICENSE +202 -0
  5. data/README.md +218 -0
  6. data/Rakefile +41 -0
  7. data/google-api-client.gemspec +43 -0
  8. data/lib/cacerts.pem +2183 -0
  9. data/lib/compat/multi_json.rb +19 -0
  10. data/lib/google/api_client.rb +750 -0
  11. data/lib/google/api_client/auth/compute_service_account.rb +28 -0
  12. data/lib/google/api_client/auth/file_storage.rb +59 -0
  13. data/lib/google/api_client/auth/installed_app.rb +126 -0
  14. data/lib/google/api_client/auth/jwt_asserter.rb +126 -0
  15. data/lib/google/api_client/auth/key_utils.rb +93 -0
  16. data/lib/google/api_client/auth/pkcs12.rb +41 -0
  17. data/lib/google/api_client/auth/storage.rb +102 -0
  18. data/lib/google/api_client/auth/storages/file_store.rb +58 -0
  19. data/lib/google/api_client/auth/storages/redis_store.rb +54 -0
  20. data/lib/google/api_client/batch.rb +326 -0
  21. data/lib/google/api_client/charset.rb +33 -0
  22. data/lib/google/api_client/client_secrets.rb +179 -0
  23. data/lib/google/api_client/discovery.rb +19 -0
  24. data/lib/google/api_client/discovery/api.rb +310 -0
  25. data/lib/google/api_client/discovery/media.rb +77 -0
  26. data/lib/google/api_client/discovery/method.rb +363 -0
  27. data/lib/google/api_client/discovery/resource.rb +156 -0
  28. data/lib/google/api_client/discovery/schema.rb +117 -0
  29. data/lib/google/api_client/environment.rb +42 -0
  30. data/lib/google/api_client/errors.rb +65 -0
  31. data/lib/google/api_client/gzip.rb +28 -0
  32. data/lib/google/api_client/logging.rb +32 -0
  33. data/lib/google/api_client/media.rb +259 -0
  34. data/lib/google/api_client/railtie.rb +18 -0
  35. data/lib/google/api_client/reference.rb +27 -0
  36. data/lib/google/api_client/request.rb +350 -0
  37. data/lib/google/api_client/result.rb +255 -0
  38. data/lib/google/api_client/service.rb +233 -0
  39. data/lib/google/api_client/service/batch.rb +110 -0
  40. data/lib/google/api_client/service/request.rb +144 -0
  41. data/lib/google/api_client/service/resource.rb +40 -0
  42. data/lib/google/api_client/service/result.rb +162 -0
  43. data/lib/google/api_client/service/simple_file_store.rb +151 -0
  44. data/lib/google/api_client/service/stub_generator.rb +61 -0
  45. data/lib/google/api_client/service_account.rb +21 -0
  46. data/lib/google/api_client/version.rb +26 -0
  47. data/spec/google/api_client/auth/storage_spec.rb +122 -0
  48. data/spec/google/api_client/auth/storages/file_store_spec.rb +40 -0
  49. data/spec/google/api_client/auth/storages/redis_store_spec.rb +70 -0
  50. data/spec/google/api_client/batch_spec.rb +248 -0
  51. data/spec/google/api_client/client_secrets_spec.rb +53 -0
  52. data/spec/google/api_client/discovery_spec.rb +708 -0
  53. data/spec/google/api_client/gzip_spec.rb +98 -0
  54. data/spec/google/api_client/media_spec.rb +178 -0
  55. data/spec/google/api_client/request_spec.rb +29 -0
  56. data/spec/google/api_client/result_spec.rb +207 -0
  57. data/spec/google/api_client/service_account_spec.rb +169 -0
  58. data/spec/google/api_client/service_spec.rb +618 -0
  59. data/spec/google/api_client/simple_file_store_spec.rb +133 -0
  60. data/spec/google/api_client_spec.rb +352 -0
  61. data/spec/spec_helper.rb +66 -0
  62. metadata +339 -0
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA1:
3
+ metadata.gz: a037b8f14704afdb6787c0e84faf1e3626b96f34
4
+ data.tar.gz: 6c6848b9a546e87f7e57f3ac2dc4def660cca782
5
+ SHA512:
6
+ metadata.gz: 319344b6d8c64f1620afba636921d712e78cca866b3ab3d5e81a356918e7393448d1e0caae7abd8fad40399791ca4a04f9f3dd238073d5227dcbd6973fb2ff45
7
+ data.tar.gz: 46d21c949986f164c772579a34b9971dd8dd8d0018eb9e3e8bd1a82702a9d35b8d9c0ff84a6de7da91e693833e5a777e4577de1aec005a8daedc26e845e860ab
data/CHANGELOG.md ADDED
@@ -0,0 +1,178 @@
1
+ # 0.8.8
2
+ * Do not put CR/LF in http headers
3
+
4
+ # 0.8.7
5
+ * Lock activesupport version to < 5.0
6
+
7
+ # 0.8.6
8
+ * Use discovered 'rootUrl' as base URI for services
9
+ * Respect discovered methods with colons in path
10
+
11
+ # 0.8.5
12
+ * Corrects the regression Rails 4 support in the 0.8.4 release.
13
+
14
+ # 0.8.4
15
+ * Fixes a file permission issues with the 0.8.3 release
16
+ * Fixes warnings when the library is used
17
+
18
+ # 0.8.3
19
+ * Adds support for authorization via Application Default Credentials.
20
+ # Adds support for tracking coverage on coveralls.io
21
+
22
+ # 0.8.2
23
+ * Fixes for file storage and missing cacerts file
24
+
25
+ # 0.8.1
26
+ * Fix logger in rails
27
+
28
+ # 0.8.0
29
+ * Refactored credential storage, added support for redis
30
+ * Update gem depdendencies
31
+ * Fixed retry logic to allow for auth retries independent of the overall number of retries
32
+ * Added `:force_encoding` option to set body content encoding based on the Content-Type header
33
+ * Batch requests with the service interface now inherit the service's connection
34
+ * `register_discover_document` now returns the API instance
35
+ * Added `:proxy` option to set Faraday's HTTP proxy setting
36
+ * Added `:faraday_options` option to allow passthrough settings to Faraday connection
37
+ * Drop 1.8.x support
38
+ * This will be the last release with 1.9.x support
39
+
40
+ # 0.7.1
41
+ * Minor fix to update gem dependencies
42
+
43
+ # 0.7.0
44
+ * Remove CLI
45
+ * Support for automatic retires & backoff. Off by default, enable by setting `retries` on `APIClient`
46
+ * Experimental new interface (see `Google::APIClient::Service`)
47
+ * Fix warnings when using Faraday separately
48
+ * Support Google Compute Engine service accounts
49
+ * Enable gzip compression for responses
50
+ * Upgrade to Faraday 0.9.0. Resolves multiple issues with query parameter encodings.
51
+ * Use bundled root certificates for verifying SSL certificates
52
+ * Rewind media when retrying uploads
53
+
54
+ # 0.6.4
55
+ * Pin signet version to 0.4.x
56
+
57
+ # 0.6.3
58
+
59
+ * Update autoparse to 0.3.3 to fix cases where results aren't correctly parsed.
60
+ * Fix railtie loading for compatibility with rails < 3.0
61
+ * Fix refresh of access token when passing credentials as parameter to execute
62
+ * Fix URI processing in batch requests to allow query parameters
63
+
64
+ # 0.6.2
65
+
66
+ * Update signet to 0.4.6 to support server side continuation of postmessage
67
+ auth flows.
68
+
69
+ # 0.6.1
70
+
71
+ * Fix impersonation with service accounts
72
+
73
+ # 0.6
74
+
75
+ * Apps strongly encouraged to set :application_name & :application_version when
76
+ initializing a client
77
+ * JWT/service accounts moved to signet
78
+ * Added helper class for installed app OAuth flows, updated samples & CLI
79
+ * Initial logging support for client
80
+ * Fix PKCS12 loading on windows
81
+ * Allow disabling auto-refresh of OAuth 2 access tokens
82
+ * Compatibility with MultiJson >= 1.0.0 & Rails 3.2.8
83
+ * Fix for body serialization when body doesn't respond to to_json
84
+ * Remove OAuth 1.0 logins from CLI
85
+
86
+
87
+ # 0.5.0
88
+
89
+ * Beta candidate, potential incompatible changes with how requests are processed.
90
+ * All requests should be made using execute() or execute!()
91
+ * :api_method in request can no longer be a string
92
+ * Deprecated ResumableUpload.send_* methods.
93
+ * Reduce memory utilization when uploading large files
94
+ * Automatic refresh of OAuth 2 credentials & retry of request when 401 errors
95
+ are returned
96
+ * Simplify internal request processing.
97
+
98
+ # 0.4.7
99
+
100
+ * Added the ability to convert client secrets to an authorization object
101
+
102
+ # 0.4.6
103
+
104
+ * Backwards compatibility for MultiJson
105
+
106
+ # 0.4.5
107
+
108
+ * Updated Launchy dependency
109
+ * Updated Faraday dependency
110
+ * Updated Addressable dependency
111
+ * Updated Autoparse dependency
112
+ * Removed Sinatra development dependency
113
+
114
+ # 0.4.4
115
+
116
+ * Added batch execution
117
+ * Added service accounts
118
+ * Can now supply authorization on a per-request basis.
119
+
120
+ # 0.4.3
121
+
122
+ * Added media upload capabilities
123
+ * Support serializing OAuth credentials to client_secrets.json
124
+ * Fixed OS name/version string on JRuby
125
+
126
+ # 0.4.2
127
+
128
+ * Fixed incompatibility with Ruby 1.8.7
129
+
130
+ # 0.4.1
131
+
132
+ * Fixed ancestor checking issue when assigning Autoparse identifiers
133
+ * Renamed discovery methods to avoid collisions with some APIs
134
+ * Updated autoparse dependency to avoid JSON bug
135
+
136
+ # 0.4.0
137
+
138
+ * Replaced httpadapter gem dependency with faraday
139
+ * Replaced json gem dependency with multi_json
140
+ * Fixed /dev/null issues on Windows
141
+ * Repeated parameters now work
142
+
143
+ # 0.3.0
144
+
145
+ * Updated to use v1 of the discovery API
146
+ * Updated to use httpadapter 1.0.0
147
+ * Added OAuth 2 support to the command line tool
148
+ * Renamed some switches in the command line tool
149
+ * Added additional configuration capabilities
150
+ * Fixed a few deprecation warnings from dependencies
151
+ * Added gemspec to source control
152
+
153
+ # 0.2.0
154
+
155
+ * Updated to use v1 of the discovery API
156
+ * Updated to use httpadapter 1.0.0
157
+ * Added OAuth 2 support to the command line tool
158
+ * Renamed some switches in the command line tool
159
+ * Added additional configuration capabilities
160
+
161
+ # 0.1.3
162
+
163
+ * Added support for manual overrides of the discovery URI
164
+ * Added support for manual overrides of the API base
165
+ * Added support for xoauth_requestor_id
166
+
167
+ # 0.1.2
168
+
169
+ * Added support for two-legged OAuth
170
+ * Moved some development dependencies into runtime
171
+
172
+ # 0.1.1
173
+
174
+ * Substantial improvements to the command line interface
175
+
176
+ # 0.1.0
177
+
178
+ * Initial release
data/Gemfile ADDED
@@ -0,0 +1,9 @@
1
+ source 'https://rubygems.org'
2
+
3
+ gemspec
4
+
5
+ gem 'jruby-openssl', :platforms => :jruby
6
+
7
+ if ENV['RAILS_VERSION']
8
+ gem 'rails', ENV['RAILS_VERSION']
9
+ end
data/LICENSE ADDED
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
data/README.md ADDED
@@ -0,0 +1,218 @@
1
+ # Google API Client
2
+
3
+ <dl>
4
+ <dt>Homepage</dt><dd><a href="http://www.github.com/google/google-api-ruby-client">http://www.github.com/google/google-api-ruby-client</a></dd>
5
+ <dt>Authors</dt><dd>Bob Aman, <a href="mailto:sbazyl@google.com">Steven Bazyl</a></dd>
6
+ <dt>Copyright</dt><dd>Copyright © 2011 Google, Inc.</dd>
7
+ <dt>License</dt><dd>Apache 2.0</dd>
8
+ </dl>
9
+
10
+ [![Build Status](https://secure.travis-ci.org/google/google-api-ruby-client.png)](http://travis-ci.org/google/google-api-ruby-client)
11
+ [![Dependency Status](https://gemnasium.com/google/google-api-ruby-client.png)](https://gemnasium.com/google/google-api-ruby-client)
12
+
13
+ ## Description
14
+
15
+ The Google API Ruby Client makes it trivial to discover and access supported
16
+ APIs.
17
+
18
+ ## Alpha
19
+
20
+ This library is in Alpha. We will make an effort to support the library, but we reserve the right to make incompatible changes when necessary.
21
+
22
+ ## Install
23
+
24
+ Be sure `https://rubygems.org/` is in your gem sources.
25
+
26
+ For normal client usage, this is sufficient:
27
+
28
+ ```bash
29
+ $ gem install google-api-client
30
+ ```
31
+
32
+ ## Example Usage
33
+
34
+ ```ruby
35
+ require 'google/api_client'
36
+ require 'google/api_client/client_secrets'
37
+ require 'google/api_client/auth/installed_app'
38
+
39
+ # Initialize the client.
40
+ client = Google::APIClient.new(
41
+ :application_name => 'Example Ruby application',
42
+ :application_version => '1.0.0'
43
+ )
44
+
45
+ # Initialize Google+ API. Note this will make a request to the
46
+ # discovery service every time, so be sure to use serialization
47
+ # in your production code. Check the samples for more details.
48
+ plus = client.discovered_api('plus')
49
+
50
+ # Load client secrets from your client_secrets.json.
51
+ client_secrets = Google::APIClient::ClientSecrets.load
52
+
53
+ # Run installed application flow. Check the samples for a more
54
+ # complete example that saves the credentials between runs.
55
+ flow = Google::APIClient::InstalledAppFlow.new(
56
+ :client_id => client_secrets.client_id,
57
+ :client_secret => client_secrets.client_secret,
58
+ :scope => ['https://www.googleapis.com/auth/plus.me']
59
+ )
60
+ client.authorization = flow.authorize
61
+
62
+ # Make an API call.
63
+ result = client.execute(
64
+ :api_method => plus.activities.list,
65
+ :parameters => {'collection' => 'public', 'userId' => 'me'}
66
+ )
67
+
68
+ puts result.data
69
+ ```
70
+
71
+ ## API Features
72
+
73
+ ### API Discovery
74
+
75
+ To take full advantage of the client, load API definitions prior to use. To load an API:
76
+
77
+ ```ruby
78
+ urlshortener = client.discovered_api('urlshortener')
79
+ ```
80
+
81
+ Specific versions of the API can be loaded as well:
82
+
83
+ ```ruby
84
+ drive = client.discovered_api('drive', 'v2')
85
+ ```
86
+
87
+ Locally cached discovery documents may be used as well. To load an API from a local file:
88
+
89
+ ```ruby
90
+ # Output discovery document to JSON
91
+ File.open('my-api.json', 'w') do |f| f.puts MultiJson.dump(client.discovery_document('myapi', 'v1')) end
92
+
93
+ # Read discovery document and load API
94
+ doc = File.read('my-api.json')
95
+ client.register_discovery_document('myapi', 'v1', doc)
96
+ my_api = client.discovered_api('myapi', 'v1')
97
+ ```
98
+
99
+ ### Authorization
100
+
101
+ Most interactions with Google APIs require users to authorize applications via OAuth 2.0. The client library uses [Signet](https://github.com/google/signet) to handle most aspects of authorization. For additional details about Google's OAuth support, see [Google Developers](https://developers.google.com/accounts/docs/OAuth2).
102
+
103
+ Credentials can be managed at the connection level, as shown, or supplied on a per-request basis when calling `execute`.
104
+
105
+ For server-to-server interactions, like those between a web application and Google Cloud Storage, Prediction, or BigQuery APIs, use service accounts.
106
+
107
+ As of version 0.8.3, service accounts can be configured using
108
+ [Application Default Credentials][1], which rely on the credentials being
109
+ available in a well-known location. If the credentials are not present
110
+ and it's being used on a Compute Engine VM, it will use the VM's default credentials.
111
+
112
+ ```ruby
113
+ client.authorization = :google_app_default # in a later version, this will become the default
114
+ client.authorization.fetch_access_token!
115
+ client.execute(...)
116
+ ```
117
+
118
+ This is simpler API to use than in previous versions, although that is still available:
119
+
120
+ ```ruby
121
+ key = Google::APIClient::KeyUtils.load_from_pkcs12('client.p12', 'notasecret')
122
+ client.authorization = Signet::OAuth2::Client.new(
123
+ :token_credential_uri => 'https://accounts.google.com/o/oauth2/token',
124
+ :audience => 'https://accounts.google.com/o/oauth2/token',
125
+ :scope => 'https://www.googleapis.com/auth/prediction',
126
+ :issuer => '123456-abcdef@developer.gserviceaccount.com',
127
+ :signing_key => key)
128
+ client.authorization.fetch_access_token!
129
+ client.execute(...)
130
+ ```
131
+
132
+ Service accounts are also used for delegation in Google Apps domains. The target user for impersonation is specified by setting the `:person` parameter to the user's email address
133
+ in the credentials. Detailed instructions on how to enable delegation for your domain can be found at [developers.google.com](https://developers.google.com/drive/delegation).
134
+
135
+ ### Automatic Retries & Backoff
136
+
137
+ The API client can automatically retry requests for recoverable errors. To enable retries, set the `client.retries` property to
138
+ the number of additional attempts. To avoid flooding servers, retries invovle a 1 second delay that increases on each subsequent retry.
139
+ In the case of authentication token expiry, the API client will attempt to refresh the token and retry the failed operation - this
140
+ is a specific exception to the retry rules.
141
+
142
+ The default value for retries is 0, but will be enabled by default in future releases.
143
+
144
+ ### Batching Requests
145
+
146
+ Some Google APIs support batching requests into a single HTTP request. Use `Google::APIClient::BatchRequest`
147
+ to bundle multiple requests together.
148
+
149
+ Example:
150
+
151
+ ```ruby
152
+ client = Google::APIClient.new
153
+ urlshortener = client.discovered_api('urlshortener')
154
+
155
+ batch = Google::APIClient::BatchRequest.new do |result|
156
+ puts result.data
157
+ end
158
+
159
+ batch.add(:api_method => urlshortener.url.insert,
160
+ :body_object => { 'longUrl' => 'http://example.com/foo' })
161
+ batch.add(:api_method => urlshortener.url.insert,
162
+ :body_object => { 'longUrl' => 'http://example.com/bar' })
163
+ client.execute(batch)
164
+ ```
165
+
166
+ Blocks for handling responses can be specified either at the batch level or when adding an individual API call. For example:
167
+
168
+ ```ruby
169
+ batch.add(:api_method=>urlshortener.url.insert, :body_object => { 'longUrl' => 'http://example.com/bar' }) do |result|
170
+ puts result.data
171
+ end
172
+ ```
173
+
174
+ ### Media Upload
175
+
176
+ For APIs that support file uploads, use `Google::APIClient::UploadIO` to load the stream. Both multipart and resumable
177
+ uploads can be used. For example, to upload a file to Google Drive using multipart
178
+
179
+ ```ruby
180
+ drive = client.discovered_api('drive', 'v2')
181
+
182
+ media = Google::APIClient::UploadIO.new('mymovie.m4v', 'video/mp4')
183
+ metadata = {
184
+ 'title' => 'My movie',
185
+ 'description' => 'The best home movie ever made'
186
+ }
187
+ client.execute(:api_method => drive.files.insert,
188
+ :parameters => { 'uploadType' => 'multipart' },
189
+ :body_object => metadata,
190
+ :media => media )
191
+ ```
192
+
193
+ To use resumable uploads, change the `uploadType` parameter to `resumable`. To check the status of the upload
194
+ and continue if necessary, check `result.resumable_upload`.
195
+
196
+ ```ruby
197
+ client.execute(:api_method => drive.files.insert,
198
+ :parameters => { 'uploadType' => 'resumable' },
199
+ :body_object => metadata,
200
+ :media => media )
201
+ upload = result.resumable_upload
202
+
203
+ # Resume if needed
204
+ if upload.resumable?
205
+ client.execute(upload)
206
+ end
207
+ ```
208
+
209
+ ## Samples
210
+
211
+ See the full list of [samples on Github](https://github.com/google/google-api-ruby-client-samples).
212
+
213
+
214
+ ## Support
215
+
216
+ Please [report bugs at the project on Github](https://github.com/google/google-api-ruby-client/issues). Don't hesitate to [ask questions](http://stackoverflow.com/questions/tagged/google-api-ruby-client) about the client or APIs on [StackOverflow](http://stackoverflow.com).
217
+
218
+ [1]: https://developers.google.com/accounts/docs/application-default-credentials