google-api-ruby-client: generated REST clients for Google APIs in Ruby

One gem per API, generated from Discovery Documents

The problem this repository addresses is narrow and concrete: calling a Google HTTP/JSON endpoint from Ruby without hand-writing request builders, response classes, retry logic and pagination for every service. The README states that the libraries are generated automatically from Discovery Documents, and that the code generator is hosted in the same repository. That matters because it means the surface area of each gem is derived from a machine-readable service description rather than from a human deciding which methods are pleasant to use.

The naming convention is the first thing to internalise. Gems follow the pattern google-apis-<servicename>_<serviceversion>, so the Drive V3 client is google-apis-drive_v3 and the Merchant Center client is google-apis-content_v2_1. Each gem gives you a service class, Ruby objects for the service's data structures, integration with the googleauth gem for OAuth, API keys and service accounts, and control over retry, pagination and timeouts.

Who is this for? Ruby developers working against a Google API that has no modern client, or working in an environment where gRPC is not available. It is not a general-purpose HTTP client and it is not a wrapper that makes Google's REST APIs feel idiomatic. The README is unusually direct about this: it says the class interfaces are sometimes awkward, and that for most users the modern client is recommended where one exists.

How a generated client is structured at runtime

The data flow in the README's Drive example is short enough to follow end to end. You require the per-service file, instantiate the service object, assign an authorization object, and then call methods whose names map onto the API's operations. The service object owns the HTTP/JSON connection to the REST endpoint; the returned value is a typed object, not a hash. In the example, list_files returns a response whose items collection holds file objects with attributes such as title.

Uploads and downloads are handled by passing a local path to the call rather than by constructing a multipart body yourself. create_file takes an upload_source and a content_type; get_file takes a download_dest. Retry, pagination and timeouts are described as controllable on the client, which is the layer where you would expect generated code to put them, since the generator cannot know your tolerance for latency or duplicate writes.

Authentication is delegated. The README points at googleauth or Signet for the assignment to authorization, and the Content API example shows the service-account path explicitly: Google::Auth::ServiceAccountCredentials.make_creds with a json_key_io and a scope, followed by fetch_access_token!. The scope string in that example is the full https://www.googleapis.com/auth/content URL. The client does not invent credentials; it uses whatever the auth library hands it.

Installing google-apis-drive_v3 and listing files

Installation is a normal gem install, or a Gemfile entry, using the versioned gem name. The README gives gem install as the mechanism and shows the Drive V3 gem as the example.

gem install google-apis-drive_v3

After that, require the service file and build the service object. The README's example leaves the authorization assignment as a placeholder pointing at Googleauth or Signet, so you supply credentials through one of those libraries rather than through this gem.

require 'google/apis/drive_v3'

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

files = drive.list_files(q: "title contains 'finances'")
files.items.each do |file|
  puts file.title
end

The query parameter is passed as a keyword argument, q, in the same form the Drive API documents. The response object exposes items, and each item carries a title. Note the README's own comment: this is the first page only. If you need more than one page, that is where the client's pagination control comes in, and the README does not spell out the call in this snippet.

Uploading and downloading use path arguments rather than file handles. The README shows create_file with a File metadata object, an upload_source pointing at a local path, and a content_type, then get_file with a download_dest.

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

drive.get_file(metadata.id, download_dest: '/tmp/downloaded-test.txt')

What you should see is a returned File object whose id you can reuse for the download. The README does not document what happens if the upload is retried partway through.

Service accounts against the Content API

The second README example is worth reading closely because it shows the credential path rather than eliding it. It requires both the generated client and googleauth, constructs ShoppingContentService, and builds service-account credentials from a JSON key file with an explicit scope.

require 'google/apis/content_v2_1'
require 'googleauth'

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

scope = 'https://www.googleapis.com/auth/content'

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

content.authorization.fetch_access_token!
content.list_datafeeds(merchant_id)

The merchant_id is described as coming from the dashboard, and the return value is typed as Google::Apis::ContentV2_1::ListDatafeedsResponse. Two details are easy to miss. First, fetch_access_token! is called explicitly before the API call, which means token lifecycle is your concern in this pattern rather than something the client hides. Second, the scope is a single string here; services that need several scopes require a different construction than the one shown.

Where this client is the wrong choice

The README's own recommendation is the clearest limitation: for most users, the modern client is preferred where one is available. Modern clients are produced by a different generator, combine generated code with hand-crafted functionality for some services, connect mostly to gRPC endpoints, and generally support streaming and long-running operations. The README states they are usually easier to use, more Ruby-like, and often faster. If you are working with Cloud Storage, Pub/Sub or BigQuery, the README names those services directly as cases where a more modern client may exist.

The second limitation is coverage of the awkward interface. Generated methods follow the Discovery Document, so names and argument shapes reflect the API rather than Ruby conventions. That is the cost of covering most API functionality without per-service hand work.

Third, tracing has moved. OpenCensus support in the gems is deprecated, and the README directs you to OpenTelemetry instead, configuring opentelemetry-instrumentation-http and opentelemetry-instrumentation-http_client and exporting to Cloud Trace through opentelemetry-exporter-google_cloud_trace. If your observability stack is still built on OpenCensus, this repository is not where you will find continued support for it.

Finally, the runtime floor is Ruby 3.2 or later. Older versions may work but are unsupported and not recommended, per the README.

Modern clients in google-cloud-ruby compared

The real alternative is not a third-party gem. It is the modern clients that live in the googleapis/google-cloud-ruby repository, and the difference is architectural rather than cosmetic. A simple REST client here is generated from a Discovery Document and speaks HTTP/JSON to the service's REST endpoint. A modern client is produced by a different generator, with hand-written additions for some services, and most of them connect to gRPC endpoints, with a few still backed by REST.

That transport difference is what produces the feature gap. Streaming and long-running operations are named in the README as modern-client capabilities, and they are the kind of thing a REST request-response shape does not express well. The simple clients cover most API functionality, but not every service has a modern equivalent, and the README says modern clients do not yet support all the services the simple clients cover. So the decision is usually forced by coverage, not by preference: if a modern client exists for your service, the README's advice is to use it; if it does not, this repository is the official option. The remaining case is infrastructure. If you cannot run gRPC, a simple REST client may be the only fit even where a modern client exists.

Maintenance, versioning and the Apache-2.0 licence

The last push to the default branch was on 2026-09-20, and the repository is not archived. Recent releases are all in the core gem: google-apis-core v1.2.5 on 2026-07-20, v1.2.4 on 2026-06-29, and v1.2.3 on 2026-06-11. Those are core releases, not per-service gem releases, and the README notes that the client libraries are updated regularly to track changes to the services. In practice that means your upgrade cost is mostly the cost of moving individual service gems when the underlying API changes, plus occasional core bumps.

The repository layout shows release-please-config.json and .release-please-manifest.json at the top level, which is the release automation this project uses to cut those versions. It also carries api_list_config.yaml, api_names.yaml and api_names_out.yaml, which are the configuration that drives which APIs get generated and what they are called.

The licence is Apache-2.0, with the full text in the LICENSE file at the repository root. Apache-2.0 is a permissive licence that includes an explicit patent grant, which is typically the reason a company prefers it over MIT for a dependency of this kind. This is a description of the licence, not legal advice; if the patent or notice clauses matter to your organisation, read the LICENSE file and your own policy rather than this paragraph.

Editorial conclusion

Adopt it when the service you need has no modern client, or when gRPC is not an option on your infrastructure, and you are on Ruby 3.2 or later. Do not adopt it as a default for Cloud Storage, Pub/Sub or BigQuery: the README points those users at the modern clients in google-cloud-ruby. Before committing, run gem install google-apis-drive_v3, confirm the generated method names on the service class you actually call, and check whether the versioned gem you picked is still published in step with the service's Discovery Document.

Frequently asked questions

Official sources

1. googleapis/google-api-ruby-client on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases