gapi

README

gapi: A command-line interface to Google APIs

(NOTE: This is not an official Google product)

Installation

• Install Go
• git clone https://github.com/ImJasonH/gapi
• go build, then run gapi as described below

Learning About APIs

List available APIs

$ gapi list
adexchangebuyer v1 - Lets you manage your Ad Exchange Buyer account.
adexchangebuyer v1.1 - Lets you manage your Ad Exchange Buyer account.
...

Get information about a specific API

$ gapi help calendar
Calendar API Lets you manipulate events and other calendar data.
More information: https://developers.google.com/google-apps/calendar/firstapp
Methods:
...

Get information about a specific method

$ gapi help calendar events.list
events.list Returns events on the specified calendar.
Parameters:
...

Calling API Methods

API requests print JSON to stdout. Users can use a tool like jq to slice and dice responses.

Get a resource

$ gapi urlshortener url.get --shortUrl=http://goo.gl/fUhtIm
{
 "kind": "urlshortener#url",
 "id": "http://goo.gl/fUhtIm",
 "longUrl": "https://github.com/ImJasonH/gapi/",
 "status": "OK"
}

Get certain fields of a resource

$ gapi urlshortener url.get --shortUrl=http://goo.gl/fUhtIm --fields=longUrl
{
 "longUrl": "https://github.com/ImJasonH/gapi/",
}

Authentication using Service Accounts

Service accounts allow you to authorize as a new user generated with a relationship to a given Google Cloud Console project. This can be useful when scripting access to private resources without requiring a user to be present to grant access.

First, create a Service Account using the Google Cloud Console, and download a .pem file containing your Service Account's credentials. Also download your Console project's client_secrets.json file, identifying your service account's project.

Pass the .pem and client_secrets.json to gapi using the --meta.pem and --meta.secrets flags, respectively.

Insert a new resource

$ gapi urlshortener url.insert --meta.pem=example.pem --meta.secrets=client_secrets.json --meta.inFile=url.json
{
 "kind": "urlshortener#url",
 "id": "http://goo.gl/POIxRL",
 "longUrl": "https://github.com/ImJasonH/gapi"
}

(This reads the HTTP request body from the file specified by --meta.inFile)

$ echo '{"longUrl":"https://github.com/ImJasonH/gapi"}' | gapi urlshortener url.insert --meta.pem=example.pem --meta.secrets=client_secrets.json --meta.in

(Make sure to pass the --meta.in flag to tell gapi to read from stdin)

or, for simple request bodies

$ gapi urlshortener url.insert --meta.pem=example.pem --meta.secrets=client_secrets.json --res.longUrl=https://github.com/ImJasonH/gapi

(This syntax is currently only supported for top-level request fields)

Authentication using OAuth

To access private resources belonging to a user (e.g., you, a real person), you must grant access to gapi using the OAuth protocol.

First, start an OAuth flow by calling gapi auth.start <api> <method>

This will generate a URL to go to to grant access, and will result in an authorization code being displayed in your browser. Copy that code and pass it into the following command: gapi auth.finish <code>

This will save your user credentials in a file called ~tokens.gob, and future requests requiring access to private resources will attempt to use the relevant token saved in the file. If no such token is found, you will be instructed to run auth.start again.

Note: If you have an OAuth access token generated by other means, you can pass it in using --meta.token=<token>, but be aware that such tokens are short-lived and are generally only usable for one hour.

Cloud Endpoints APIs

To use Cloud Endpoints APIs, pass the --endpoint= flag before the command or method to invoke, like so:

$ gapi --endpoint=https://go-endpoints.appspot.com/_ah/api/ list
Available methods:
...

gapi --endpoint=https://go-endpoints.appspot.com/_ah/api/ greeting greets.list
{
 "items": [
    ...
  ]
}

---

License

Copyright 2014 Google, Inc.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.