Merge branch 'master' of https://github.com/google/google-api-ruby-client

[arvados.git] / README.md

diff --git a/README.md b/README.md
index 76e374ea3d35497131fae2856c4a02f43b861ee8..03124d5ccc7afe97574d4150370b6a57c3fe3a2a 100644 (file)
--- a/README.md
+++ b/README.md
@@ -15,6 +15,10 @@
 The Google API Ruby Client makes it trivial to discover and access supported
 APIs.
 
+## Alpha
+
+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.
+
 ## Install
 
 Be sure `https://rubygems.org/` is in your gem sources.
@@ -83,8 +87,13 @@ drive = client.discovered_api('drive', 'v2')
 Locally cached discovery documents may be used as well. To load an API from a local file:
 
 ```ruby
+# Output discovery document to JSON
+File.open('my-api.json', 'w') do |f| f.puts MultiJson.dump(client.discovery_document('myapi', 'v1')) end
+
+# Read discovery document and load API
 doc = File.read('my-api.json')
-my_api = client.register_discovery_document('myapi', 'v1', doc)
+client.register_discovery_document('myapi', 'v1', doc)
+my_api = client.discovered_api('myapi', 'v1')
 ```
 
 ### Authorization
@@ -110,6 +119,14 @@ client.execute(...)
 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
 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).
 
+### Automatic Retries & Backoff
+
+The API client can automatically retry requests for recoverable errors. To enable retries, set the `client.retries` property to
+the number of additional attempts. To avoid flooding servers, retries invovle a 1 second delay that increases on each subsequent retry.
+In the case of authentication token expiry, the API client will attempt to refresh the token and retry the failed operation - this
+is a specific exception to the retry rules.
+
+The default value for retries is 0, but will be enabled by default in future releases.
 
 ### Batching Requests
 
@@ -176,26 +193,6 @@ if upload.resumable?
 end
 ```
 
-## Command Line
-
-Included with the gem is a command line interface for working with Google APIs.
-
-```bash
-# Log in
-google-api oauth-2-login --client-id='...' --client-secret='...' --scope="https://www.googleapis.com/auth/plus.me"
-
-# List the signed-in user's activities
-google-api execute plus.activities.list --api=plus -- userId="me" collection="public"
-
-# Start an interactive API session
-google-api irb
->> plus = $client.discovered_api('plus')
->> $client.execute(plus.activities.list, {'userId' => 'me', 'collection' => 'public'})
-=> # returns a response from the API
-```
-
-For more information, use `google-api --help`
-
 ## Samples
 
 See the full list of [samples on Github](https://github.com/google/google-api-ruby-client-samples).