Skip to end of metadata
Go to start of metadata

Many of Google's apis use the Google Data Protocol as the base for accessing their services.  GData uses a RESTish structure of calls, AtomPub (JSON support is nascent) for the format, an OAuth for security.  

GData Protocol

The documentation given for the protocol is given below:

Protocol Basics

If you are familiar with RSS, you should understand the concept of feeds and entries.  Atom allows you to expand the set of elements by using the namespace feature of XML.

Keys

Keys allow your app to access google data.  To get your own set of keys click here.

The following is an example of using your Google Data keys in a KRL application:

Scope

Google gives scope to an OAuth token.  An OAuth token scope means that the OAuth token is authorized for a specific API.  As part of the OAuth dance, your ruleset needs to check to see if the ruleset has already been authorized. 

Creating an App

When you create your app, you need to specify ahead of time what apis you want to access via OAuth.  The following is an example of using OAuth for google data.

This rule set has a rule that checks to see if the user has a valid OAuth token.  If no valid token then it executes the google:authorize action passing it the string calendar.  If this action is fired then all other rules will stop firing and the user with then use OAuth to authorize the app through google.  When the user returns to the current page the ruleset will be re-evaluated.  

Calendar

Calendar requests generally contain 4 elements.  Where possible, KRL will try to provide defaults for theses values, and will take care of formatting the request properly.

  • Feed
  • Visibility
  • Projection
  • Parameters

Feed

Calendar has 4 feeds to choose from: calendar, event, comment, settings.

The calendar feed can identify calendars the user has created and to which he subscribes.  These feeds are the 'metafeed', 'allcalendars', and 'owncalendars'.  Metafeed and allcalendars have similar information, but allcalendars also provides user preference details for example calendar color, visibility, and whether or not it is selected.  FYI: Allcalendars is also a read/write feed, but KRL does not provide write access to Google feeds.  

Event returns data about individual events listed in the user's calendars.  By default, the user is identified by the authorization token that KRL provides.  It is possible to specify a user, but without a token, you can only access events with a visibility of "public". With appropriate parameters (like start-max, futureevents, and queries) you can search for the specific events.  If you already know the event id, you can specify that and limit your results to just one entry.  

The comment feed is available if you know the event id to which the comments are attached.

The settings feed returns the user preferences.  If you know the name of a particular preference, you can access that individual value. 

Visibility

Acceptable values are public and private.  Private visibility is only enabled for authorizations.  Public visibility does not require authentication, but will be unavailable if the user has disabled sharing. 'private' is the default value.

Projection

 Projection is a name for how much and what types of data you are requesting.  Allowed values are:

NameDescription
fullFull-fidelity feed; contains all event properties, but comments aren't included inline.
full-noattendeesSame as full, but without any <gd:who> elements.
composite

Attendees-only feed. Contains minimal event information, but includes <gd:who>.

attendees-onlyFree/busy feed. Contains minimal event information, but includes<gd:when>
basic

Basic Atom feed without any extension elements

'full' is the default value for KRL requests.

You can also find the allowed values from Google's Projections page. 

Parameters

Parameters include the options common to all GData APIs and those specific to Calendar

Examples

Here is a ruleset that grabs the events from a user's calendar that have been updated today:

Get the events scheduled for a specific timeframe:

Get the events scheduled for a specific timeframe and display with the West Coast timezone

Get the user's first (10) upcoming events

 

 

 

 

 

Labels: