Getting Started

This document provides all the basic information you need to start using the library. It covers important library concepts, shows examples for various use cases, and gives links to more information.

Setup

Installing the library

You can install the client library using standard Ruby tools. Be sure to follow the installation instructions.

Google Developers Console

Any development you do using the Google API Client Library for Ruby will have to be tied to a Developers Console project, so if you haven't created one yet, now's a great time!

Go to the Google Developers Console. Click Create Project, enter a name, and click Create.

Authentication and authorization

It is important to understand the basics of how API authentication and authorization are handled. All API calls must use either simple or authorized access (defined below). Many API methods require authorized access, but some can use either. Some API methods that can use either behave differently, depending on whether you use simple or authorized access. See the API's method documentation to determine the appropriate access type.

1. Simple API access (API keys)

These API calls do not access any private user data. Your application must authenticate itself as an application belonging to your Google Developers Console project. This is needed to measure project usage for accounting purposes.

API key: To authenticate your application, use an API key for your Developers Console project. Every simple access call your application makes must include this key.

2. Authorized API access (OAuth 2.0)

These API calls access private user data. Before you can call them, the user that has access to the private data must grant your application access. Therefore, your application must be authenticated, the user must grant access for your application, and the user must be authenticated in order to grant that access. All of this is accomplished with OAuth 2.0 and libraries written for it.

Scope: Each API defines one or more scopes that declare a set of operations permitted. For example, an API might have read-only and read-write scopes. When your application requests access to user data, the request must include one or more scopes. The user needs to approve the scope of access your application is requesting.

Refresh and access tokens: When a user grants your application access, the OAuth 2.0 authorization server provides your application with refresh and access tokens. These tokens are only valid for the scope requested. Your application uses access tokens to authorize API calls. Access tokens expire, but refresh tokens do not. Your application can use a refresh token to acquire a new access token.

Client ID and client secret: These strings uniquely identify your application and are used to acquire tokens. They are created for your project on the Developers Console. There are three types of client IDs, so be sure to get the correct type for your application:

Building a client and calling an API

This section describes the basics of how to create a client for an API and make a simple request. The Drive API is used as an example, but the process is the same for every API supported by the client.

Building a client object

The client library includes generated classes for each supported API. To use an API, you need to require the correct file and instantiate a service. To use the Drive API:

require 'google/apis/drive_v2'

drive = Google::Apis::DriveV2::DriveService.new

Methods and requests

Available methods for an API are declared in it's service class. Available methods for an API can be found in the reference documentation for the library.

Continuing with the previous Google Drive example, a call to retrieve a list of files and print their names would look like:

  files = drive.list_files()
  files.items.each do |file|
    puts file.name
  end

Calls return data object if successful. Unsucessfull requests raise errors that provide additional details about the cause.

Finding information about the APIs

You can use the APIs Explorer to browse APIs, list available methods, and even try API calls from your browser. Refer to the reference documentation for the library for additional details about how to call an API with the library.