My favorites | Sign in
Project Home Downloads Wiki Issues Source
Search
for
DiscoveryManual  
How to use the Discovery APIs
Updated Oct 13, 2011 by jh...@google.com

Introduction

Support for non-GData APIs has been added! This support is done by using Google’s Discovery service. While the usage of the new services is similar to the existing syntax, there are many key differences between them. This page is meant to introduce the new features.

A few things to note:

  • These features are currently in alpha. Some things may be a little buggy.
  • The interfaces are autogenerated. This means that new services can (and will) be added automatically as they become available. However, it also means that complicated APIs will have similarly complicated syntax.
  • Features have been added to make it easier to use the new services.
  • The new APIs have quotas. For power users, it is recommended that they use the API Console to use their own credentials.

If you want to play around with the new services in a GUI, check out the API Explorer.

What You’ll Need

1. Make sure that your version of GoogleCL is up to date. There is not currently a download available for the new features, so you will need to check it out of the subversion repository.

2. Install the client that supports the new services, which can be found at this page. If for some reason you want to use the new features of GoogleCL but not the Discovery APIs, then skip this step. (You’ll essentially have no new functionality)

3. Install GoogleCL.

Usage

The usage of the new APIs is, in general, similar to existing syntax. A few notes:

  • Instead of having services and tasks, the new APIs have services, resources, and methods.
  • Services and methods are pretty much the same as the existing services/tasks
  • Resources could be thought of a service within a service. For example, the Tasks service has two resources: one for managing the individual tasks, and one for managing the different tasklists.

Commands generally take the form

$ google <service> <resource> <method> <parameters>

Like before, GoogleCL will attempt to identify what your intent is. Some of the new commands can be long compared to the older commands, so features have been added to shorten the length of a command and implicitly identify what should be done. Doing so may not always be stable - as mentioned, the services are autogenerated, so it is possible that their usage will change, and some assists may no longer work. While this should be rare, it is still recommended that if stability is required, then the full command is used.

For example, a command to create a new shortened URL using Url Shortener could be:

$ google urlshortener v1 url insert --body '{"longUrl": "www.google.com"}'

Some of this may be trimmed down - for example, GoogleCL will use the newest version of the API by default. Additionally, UrlShortener only has one resource, url, so it is automatically selected. Finally, parameters can be inserted automatically into the body parameter. This shortens the command to:

$ google urlshortener insert --longUrl www.google.com

There are also a few other features, such as matching unmarked parameters, and prompting for missing commands may be turned on or off.

The Help Function

The help function works a bit differently for the new APIs. For one, it can provide much more specific information on different parts of the service. The most useful commands are probably the following:

$ google help <service> - Describes a service, lists resources

$ google help <service> --verbose - Lists all information regarding a service

$ google help <service> <resource> <method> - Lists information on a method

$ google help <service> <resource> <method> --verbose - Lists all the information regarding a method

$ google help <service> <resource> <method> <parameter> - Lists information regarding a parameter

$ google help <service> schemas <schema> - Lists information regarding a schema

The Body Parameter and Schemas

Some methods require a JSON request to be attached, which may be specified using the body parameter. Alternatively, it is possible for fields to be put into the body automatically. Example:

$ google urlshortener insert --body '{"longUrl": "www.google.com"}'

This may be shortened to:

$ google urlshortener insert --longUrl www.google.com

Information on a schema can be found using the help <service> schemas <schema> command mentioned above.

Two things of note:

  • It is not currently possible to know which fields an the schema are required or mutable for a method, unlike for the normal parameters
  • Nesting may be required for some schemas.

Example of nesting - note that in the following command, the body has a subfield, ‘object’. If one were to investigate the schema, they would see that the ‘object’ field corresponds to an object, opposed to a string or other type of information. Arrays are also possible for some methods.

$ google buzz activities insert --userId @me --title GoogleCL --object '{"content": "Posting from GoogleCL!", "type": "note"}'

$ google buzz activities insert --userId @me --body '{"title": "GoogleCL", "object": {"content": "Posting from GoogleCL!", "type": "note"}}'

The Fields Parameter

The fields parameter is also used by the new APIs to submit partial requests. You may look at a method to identify its response schema, and look at that schema to determine which fields you want to see.

  • Having no fields specified returns the entire response
  • Nested fields may be specified with <field>/<subfield> or <field>(<subfield1>,<subfield2>).

Example:

$ google urlshortener get http://goo.gl/ENYw5

  • status: OK
  • kind: urlshortener#url
  • id: http://goo.gl/ENYw5
  • longUrl: http://www.google.com/

$ google urlshortener get http://goo.gl/ENYw5 --fields id,longUrl

  • longUrl: http://www.google.com/
  • id: http://goo.gl/ENYw5

Configration Options and Defaults

The config file may be edited using the command edit config. Once there, it is possible to edit GoogleCL's settings and defaults.

  • GData defaults may be edited as usual
  • The new APIs have their defaults stored by method instead of by service. The heading should be the method's ID.
  • For example, the ID of urlshortener url insert is urlshortener.url.insert. If you're uncertain, use help <...> --verbose.

The following is a partial list of config settings:

  • prompt: (none, required, all) - sets what missing parameters are prompted for
  • editmode: (editor, cl) - editor -> if body is missing, launches editor, otherwise prompts on command line
  • formatting: (none, pprint, clean) - Determines which style of output is displayed. JSON is displayed by none and pprint, so consider using those if you intend to do scripting. If you don’t want JSON, clean will remove the wrappings.

Additionally, if you intend to heavily use the new APIs and are concerned about the quota, it is recommended that you make use of the API console and enter the following fields:

  • client_id: (string)
  • client_secret: (string)
  • devkey2: (string)

Authorization

The new APIs make use of OAuth2. When you first use a new service, it will prompt you to authorize its usage. If you wish to revoke the credentials for some reason, it is possible to do so online. Alternatively, the local credentials may be deleted and reprompted for by using the --force-auth flag.

Tips for Scripters/Power Users

If you intend to use the new services for scripting, there are a few things you can do to make it easier.

Firstly, get your own unique project credentials from the API Console.

1. Go to the API Console page and create a new project.

2. Select which APIs you intend to use with GoogleCL (Buzz, Tasks, etc).

3. Select the ‘API Access’ tab.

4. Get your OAuth2 credentials. You’ll need to give your project a name.

5. Copy your Client ID, Client secret, and API key.

6. Open your config file.

7. Under the ‘general’ section, add the fields ‘client_id’, ‘client_secret’, and ‘devkey2’ corresponding to the credentials you just copied.

The advantage of this is that you’ll be able to manage your own quota and what services you want to use. All projects (including GoogleCL) have a limited number of requests per day that they may make, so having your own unique project will allow you to make more requests.

One additional thing you may wish to do is enable JSON output, which can be easier for parsing and scripting. It is pprint by default.

To do so, edit your config settings. Under the ‘general’ section, add the line formatting = pprint or formatting = none You can also disable prompting and edit other config settings.

For scripting, it is also recommended that the full method path (especially version) is used. This usually won’t be an issue, but, as mentioned, the services are autogenerated, and it’s possible that it will change over time.

Example Scripts

Creating a new short URL

$ google urlshortener insert --longUrl www.google.com

$ google urlshortener insert --body '{"longUrl": "www.google.com"}'

Retrieving a shortened URL

$ google urlshortener get --shortUrl http://goo.gl/ENYw5

Getting a list of tasks

$ google tasks tasks list --tasklist @default

Creating a new task

$ google tasks tasks insert @default --title "Test GoogleCL"

$ google tasks tasks insert @default --body '{"title": "Test GoogleCL"}'

Posting something to Buzz

$ google buzz activities insert --userId @me --title GoogleCL --object '{"content": "Posting from GoogleCL!", "type": "note"}'

$ google buzz activities insert --userId @me --body '{"title": "GoogleCL", "object": {"content": "Posting from GoogleCL!", "type": "note"}}'

Translate something to another language

$ google translate translations "Hello, world" es

Walkthrough

All of this may be a bit confusing, so let’s walk through using a service step by step.

Let’s say you want to view your list of tasks and add a new item to it.

First, pull up the help screen.

$ google help

  • Welcome to the Google CL tool!
  • <...>
  • The available services are
  • 'picasa', 'blogger', 'youtube', 'docs', 'contacts', 'calendar', 'finance'
  • and via Discovery:
  • 'adexchangebuyer', 'audit', 'books', 'buzz', 'customsearch', 'diacritize', 'discovery', 'freebase', 'moderator', 'pagespeedonline', 'prediction', 'shopping', 'siteVerification', 'taskqueue', 'tasks', 'translate', 'urlshortener'
  • <...>

Look at the list of available Discovery services. One of those items is ‘tasks’ - that must be what you want!

Next, pull up the help for tasks.

$ google help tasks

  • Lets you manage your tasks and task lists.
  • Resources: tasks, tasklists

Tasks has two resources available, tasks and tasklists. You’re not intending to manage your lists, just the tasks on them, so call the help for the tasks resource.

$ google help tasks tasks

  • Methods: insert, get, clear, move, list, update, patch, delete

List and insert are the two methods we’re interested in here. Let’s do list first.

$ google help tasks tasks list

  • Returns all tasks in the specified task list.
  • Requires: tasklist Optional: dueMax, showDeleted, updatedMin, completedMin, maxResults, showCompleted, pageToken, completedMax, showHidden, dueMin

The method requires a tasklist, but you don’t know what that is! Let’s examine it.

$ google help tasks tasks list tasklist

  • required: True
  • type: string
  • description: Task list identifier.
  • location: path

Okay, so it’s a string corresponding to an ID for a task list. Pretty self explanatory. You aren’t sure what you have available though, so it looks like you do need to use the tasklists resource.

$ google help tasks tasklists

  • Methods: insert, get, list, update, patch, delete

List seems like the best choice.

$ google help tasks tasklists list

  • Returns all the authenticated user's task lists.
  • Optional: pageToken, maxResults

Conveniently, it doesn’t require any parameters, so let’s execute!

$ google tasks tasklists list

  • Go to the following link in your browser:
  • <link>

You haven’t used GoogleCL for the tasks service yet, so it requires authorization. Access the link, click to allow access, and go back to the command line.

  • Successfully retrieved access token: <...>
  • You have successfully authenticated.
  • items:
  • kind: tasks#taskList
  • id: verylongidyouwouldneverknow
  • selfLink: https://www.googleapis.com/tasks/v1/users/@me/lists/verylongidyouwouldneverknow
  • title: Your list
  • kind: tasks#taskLists
  • etag: <...>

Okay, so your tasklist’s id is some random number. That seems very annoying to remember. Fortunately, you can save it as a default setting. To do so, first you’ll need to know the id of the task you want to set it as a default as. To do so, call up the verbose help for your method.

$ google help tasks tasks list -v

  • scopes: https://www.googleapis.com/auth/tasks, https://www.googleapis.com/auth/tasks.readonly
  • description: Returns all tasks in the specified task list.
  • parameters: dueMax, tasklist, showDeleted, updatedMin, completedMin, maxResults, showCompleted, pageToken, completedMax, showHidden, dueMin
  • response: $ref
  • httpMethod: GET
  • parameterOrder: tasklist
  • path: lists/{tasklist}/tasks
  • id: tasks.tasks.list

As you can see, the id is ‘tasks.tasks.list’. Next, launch the config editor.

$ google edit config

This will open your config file for editing. To set a default, create a heading consisting of the method’s id, and then add the desired default parameter name and value. In this case, it would be:

  • [tasks.tasks.list]
  • tasklist = verylongidyouwouldneverknow

(alternatively, you could also just also just say the id is @default, which returns your default task list.)

Now, you can (finally) view your tasks!

$ google tasks tasks list

You’ll get a long list of your tasks and all the data describing them. However, looking over the output, you’re only interested in the ‘title’ field. Fortunately, you can set what data is contained in the response. You can see that ‘title’ is a subfield of ‘items’. So go to the config editor again and enter under the heading:

  • fields = items/title

The next time you call that method, it will only return the titles of each of the items.

First mission is done. Now to insert a new task.

Pull up the help for the method.

$ google help tasks tasks insert

  • Creates a new task on the specified task list.
  • Requires: tasklist Optional: parent, previous
  • Request schema: Task

Okay, so it needs a tasklist again. You can reuse the same id from last time and enter it in the config file under a new heading. But what’s with this Task schema? Let’s pull up the help on it.

$ google help tasks schemas Task

  • type: object
  • id: Task
  • properties: status, kind, updated, parent, title, deleted, completed, due, etag, notes, position, hidden, id, selfLink

You know the only field that matters to you right now is the title, so that will be the one field you enter. Now you just have to take care of the schema formatting.

Schemas correspond to a JSON object, and are entered under the 'body' parameter. So one valid method call would be:

$ google tasks tasks insert --body '{"title": "Use GoogleCL"}'

There are a few issues with this though - for one, JSON can be annoying to enter on the command line, since you need to make sure that the quotes don’t vanish and all the brackets are correct (Note: quotes are required around JSON field names, and don’t vanish in interactive mode). Fortunately, GoogleCL is able to automatically put body parameters into the JSON. Thus, the method is simplified to:

$ google tasks tasks insert --title 'Use GoogleCL!'

And that's it! You've successfully created a new task.

Powered by Google Project Hosting