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.
The documentation given for the protocol is given below:
- Google Data Protocol
- Atom Syndication Format (RFC 4287)
- Google Calendar API Reference
- Google Data Common Elements
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 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:
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 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.
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.
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 is a name for how much and what types of data you are requesting. Allowed values are:
|full||Full-fidelity feed; contains all event properties, but comments aren't included inline.|
|full-noattendees||Same as full, but without any <gd:who> elements.|
Attendees-only feed. Contains minimal event information, but includes <gd:who>.
|attendees-only||Free/busy feed. Contains minimal event information, but includes<gd:when>|
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.
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