nginx-sso/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 -u 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 (
    "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.

There are several ways to do authentication. They will all involve the package golang.org/x/oauth2 in some way.

3-legged OAuth

For 3-legged OAuth (your application redirecting a user through a website to get a token giving your application access to that user's resources), you will need to create an oauth2.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},
    }

... and then use the AuthCodeURL, Exchange, and Client methods on it. For an example, see: https://godoc.org/golang.org/x/oauth2#example-Config

For the redirect URL, see https://developers.google.com/identity/protocols/OAuth2InstalledApp#choosingredirecturi

Service Accounts

To use a Google service account, or the GCE metadata service, see the golang.org/x/oauth2/google package. In particular, see google.DefaultClient.

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},
    })
    oauthConfig := &oauth2.Config{ .... }
    var token *oauth2.Token = .... // via cache, or oauthConfig.Exchange
    httpClient := oauthConfig.Client(ctx, token)
    svc, err := urlshortener.New(httpClient)
    ...

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. (the examples use some functions in main.go in the same directory)

Error Handling

Most errors returned by the Do methods of these clients will be of type googleapi.Error. Use a type assertion to obtain the HTTP status code and other properties of the error:

    url, err := svc.Url.Get(shortURL).Do()
    if err != nil {
        if e, ok := err.(*googleapi.Error); ok && e.Code == http.StatusNotFound {
            ...
        }
    }