registry/vendor/google.golang.org/api/GettingStarted.md

Getting Started with the Google APIs for Go

Getting Started

This is a quick walk-through of how to get started with the Google APIs for Go.

Background

The first thing to understand is that the Google API libraries are auto-generated for each language, including Go, so they may not feel like 100% natural for any language. The Go versions are pretty natural, but please forgive any small non-idiomatic things. (Suggestions welcome, though!)

Installing

Pick an API and a version of that API to install. You can find the complete list by looking at the directories here.

For example, let's install the urlshortener's version 1 API:

$ go get google.golang.org/api/urlshortener/v1

Now it's ready for use in your code.

Using

Once you've installed a library, you import it like this:

package main

import (
    "golang.org/x/net/context"
    "golang.org/x/oauth2"
    "golang.org/x/oauth2/google"
    "google.golang.org/api/urlshortener/v1"
)

The package name, if you don't override it on your import line, is the name of the API without the version number. In the case above, just urlshortener.

Instantiating

Each API has a New function taking an *http.Client and returning an API-specific *Service.

You create the service like:

    svc, err := urlshortener.New(httpClient)

OAuth HTTP Client

The HTTP client you pass in to the service must be one that automatically adds Google-supported Authorization information to the requests.

The best option is to use "golang.org/x/oauth2", an OAuth2 library for Go. You can see how to set up and use oauth2 with these APIs by checking out the example code.

In summary, you need to create an OAuth config:

    var config = &oauth2.Config{
        ClientID:     "", // from https://console.developers.google.com/project/<your-project-id>/apiui/credential
        ClientSecret: "", // from https://console.developers.google.com/project/<your-project-id>/apiui/credential
        Endpoint:     google.Endpoint,
        Scopes:       []string{urlshortener.UrlshortenerScope},
    }

Then you need to get an OAuth Token from the user. This involves sending the user to a URL (at Google) to grant access to your application (either a web application or a desktop application), and then the browser redirects to the website or local application's webserver with the per-user token in the URL.

Once you have that token,

    httpClient := newOAuthClient(context.Background(), config)

Then you're good to pass that client to the API's New function.

Using API Keys

Some APIs require passing API keys from your application. To do this, you can use transport.APIKey:

    ctx = context.WithValue(context.Background(), oauth2.HTTPClient, &http.Client{
        Transport: &transport.APIKey{Key: developerKey},
    })
    httpClient := newOAuthClient(ctx, config)

Using the Service

Each service contains zero or more methods and zero or more sub-services. The sub-services related to a specific type of "Resource".

Those sub-services then contain their own methods.

For instance, the urlshortener API has just the "Url" sub-service:

    url, err := svc.Url.Get(shortURL).Do()
    if err != nil {
        ...
    }
    fmt.Printf("The URL %s goes to %s\n", shortURL, url.LongUrl)

For a more complete example, see urlshortener.go in the examples directory.