google-api-ruby-client

# Simple REST Clients for Google APIs

This repository contains a set of simple client libraries for various Google APIs. These libraries are generated automatically from [Discovery Documents](https://developers.google.com/discovery), and the code generator is also hosted here in this repository.

Each client provides:

* A client object that connects to the HTTP/JSON REST endpoint for the service.
* Ruby objects for data structures related to the service.
* Integration with the googleauth gem for authentication using OAuth, API keys, and service accounts.
* Control of retry, pagination, and timeouts.

These client libraries are officially supported by Google, and are updated regularly to track changes to the service. However, many Google services, especially Google Cloud Platform services such as Cloud Storage, Pub/Sub, and BigQuery, may provide a more modern client that is easier to use and more performant. See the section below titled ["Which client should I use?"](#which-client-should-i-use) for more information.

## Using the clients

The client gems are named according to the pattern `google-apis-<servicename>_<serviceversion>`. For example, the client for the Google Drive V3 API is `google-apis-drive_v3`.

Install the client using `gem install` or by adding it to your `Gemfile`. Then, to use it, require the file and instantiate the service. For example to use the Drive API:

```ruby
require 'google/apis/drive_v3'

drive = Google::Apis::DriveV3::DriveService.new
drive.authorization = ... # See Googleauth or Signet libraries

# Search for files in Drive (first page only)
files = drive.list_files(q: "title contains 'finances'")
files.items.each do |file|
  puts file.title
end

# Upload a file
metadata = Google::Apis::DriveV3::File.new(name: 'test.txt')
metadata = drive.create_file(metadata, upload_source: '/tmp/test.txt', content_type: 'text/plain')

# Download a file
drive.get_file(metadata.id, download_dest: '/tmp/downloaded-test.txt')
```

Following is another example using the Content API (Google Merchant Center), provided by the `google-apis-content_v2_1` gem:

```ruby
require 'google/apis/content_v2_1'
require 'googleauth' # https://github.com/googleapis/google-auth-library-ruby

content = Google::Apis::ContentV2_1::ShoppingContentService.new

scope = 'https://www.googleapis.com/auth/content'
merchant_id = # Merchant ID found on dashboard

content.authorization = Google::Auth::ServiceAccountCredentials.make_creds(
  json_key_io: File.open('./content-api-key.json'),
  scope: scope)

content.authorization.fetch_access_token!
# Service methods: https://rubydoc.info/gems/google-apis-content_v2_1/Google/Apis/ContentV2_1/ShoppingContentService
content.list_datafeeds(merchant_id) # Returns Google::Apis::ContentV2_1::ListDatafeedsResponse
```

For more detailed information, see the [Usage Guide](https://github.com/googleapis/google-api-ruby-client/blob/main/docs/usage-guide.md).

## Which client should I use?

Google provides two types of Ruby