Accessing Google APIs using Restty

Starting with version 0.22, Restty includes authentication module restty-oauth2 supporting OAuth 2.0 authentication protocol utilized by Google in theirs APIs. Even better, Restty also includes full set of Active JSON templates for accessing Google Tasks and URL Shortener APIs (see gtasks and gshort profiles).

In order to make oauth2 module available for Active JSON templates, you need to register it using _config.js file for your profile.

Enabling OAuth module in Restty config

1. Enabling OAuth module in Restty config

Section contextObjects of the config file is used to register Context Objects that will be available in Active JSON templates. Context Objects have to be defined as key – value pairs. Key determines the name of the object and the value provides required information for the object to be created. It may be either a string value (in this case it has to define a java class name for the object implementation, or it may be an object (in this case it must have an parameterimplementation that has to provide the java class name). Additionally, there may be a parametersettingsthat can be used to configure that Context Object. In our case, it has a single configuration parameter useCache which is set to true. This parameter determines whether the oauth module has to persist received authentication information in a file. The information is stored in the plain text file, so be careful, with this option. However, if you disable the cache, you will be asked to grant access to you data every time you run Restty command that requires authentication, which is a bitinconvenient. Remember, that you may always go to .\work directory and remove files that containsensitive information (the files have names starting withrestty-oauth2_).

Section settings is optional in the Context Object configuration. If omitted, the default settings will be applied. As foruseCachedefault value is true, instead of using complex object to describe $googleAuth Context Object we could have used the same short notation as we used to define$args.

For the commands that require authenticated access, all you need to do is add parameter Authorizationto the header description.

Providing authorization token to Google API

2. Providing authorization token to Google API

As you can see, we assigned string value “Bearer ” + authorization token returned by $googleAuthto the HTTP header parameter Authorization. This code normally goes to _prototype.js, so you don’t need to include it into the individual command templates.

Method getToken, receives two arguments:

  • scope – this is an authentication scope specific to the current Google API. This argument may be either string of array of string when several scopes are used. For the full set of available scopes, please, refer to Google API reference.
  • tag – this argument is used to cache authentication information. Information for every tag is stored separately. You have to use different tags for different scopes. Also, using different tags allows accessing different accounts – all you need to do is use a separate tag for each account.
Multiple accounts support

3. Multiple accounts support

When there is no cached authentication information available or you disabled the caching, you will be asked to grant Restty access to the specific Google API.

Grant Access Confirmation

4. Grant Access Confirmation

For the Restty command to succeed, you have to press “Allow access” button. This will provide Restty with the authorization tokens to perform trusted API calls.

Google URL Shortener - Access granted

5. Google URL Shortener - Access granted

In the case, when a command has many input arguments (especially, when many of them are optional), it would be inconvenient to pass values sequentially one-by-one, so they can be passed by name like shown on the following screenshot for insert-task command utilizingGoogle Tasks API.

Google Tasks API - passing arguments by name

6. Google Tasks API - passing arguments by name

Using Restty is easy – download it and see for yourself.

For your reference, here is a complete list of Google URL Shortener commands implemented in Restty with the arguments:

  • get– returns information about single url
    • url – required – short url for lookup
    • fields – optional,default = “short”determines, whether to show additional information for the specified url (allowed values: [short | all]). For the “short” option it returns original url value and clicksanalytics- number of clicks for the url in specific intervals (two hours, day, week, …). For the “all” it returns all available data including analytics
  • list– returns list of all urls associated with user’s account. The number of urls returned, is limited by 30 items. If there are more urls available, pageTokenargument may be used to navigate through the result.
    • pageToken – optional- can be used to navigate through the result when there are more then 30 items available.
    • fields-optional,default = “short”determines, whether to show additional information for the specified url (allowed values: [short | all]). For the “short” option it returnsoriginal and short url values. For the “all” it returns all available data including analytics
  • new– creates new short url from the provided original url
    • url – required – original url

And for Google Tasks API:

  • get-list – returns detailed information about a single Task List, if idis provided, otherwisereturns list of available Task Lists.
    • id – optional – Task List id
    • maxResults – optional, default = 20 – max results returned per page
    • pageToken – optional -can be used to navigate through the result when there are more then maxResultsitems available
  • insert-list– creates a new Task List with the given title
    • title – required – title of the Task List
  • update-list– updates an existing Task List title
    • id – required – Task List id to be updated
    • title – required – new title
  • clear-list– clears (hides completed tasks) specified Task List
    • list – required – Task List id
  • delete-list– deletes specified Task List
    • id -required- Task List id
  • get-task -returns detailed information about a single Task, ifidis provided, otherwisereturns list of available Tasks
    • id – optional – Task id
    • list – optional, default = “@default” – Task List id
    • showCompleted – optional, default = false -flag indicating whether to show completed Tasks
    • maxResults – optional, default = 20 -max results returned per page
    • pageToken – optional -can be used to navigate through the result when there are more thenmaxResultsitems available
    • updatedMin -optional- lower bound for Tasks update date inRFC 3339 format (for example2012-05-28T12:00:00).
    • completedMax-optional- higher bound for Tasks completed dateinRFC 3339 format
    • completedMin -optional- lower bound for Tasks completed dateinRFC 3339 format
    • dueMax-optional- higher bound for Tasks due dateinRFC 3339 format
    • dueMin -optional- lower bound for Tasks due dateinRFC 3339 format
    • showDeleted -optional, default = false- flag indicating whether to show deleted Tasks
    • showHidden-optional, default = false- flag indicating whether to show hidden Tasks
    • fields-optional,default = “short”- determines level of details to request. Allowed values [min | short | all]. Min returns only titles;short -id, title, status, due; all – returns all fields
  • insert-task– creates a new Task
    • list-optional,default = “@default”- Task List id
    • parent-optional – parent Task id – to create a sub-Task
    • previous -optional- previous Task id – to insert a Task into specified position
    • title-required- title of the new Task
    • notes-optional-description of the new Task
    • due-optional-due date of the new TaskinRFC 3339 format
    • completed-optional, default = false – flag showing whether a Task is completed
  • move-task– moves a Task to a new position
    • id – required – Task id
    • list – optional, default = “@default” – Task List id
    • parent -optional- parent Task id – to make the Task a sub -Task
    • previous-optional- previous Task id – to move the Task into specified position
  • update-task– updates an existing Task
    • id-required- Task id
    • list-optional,default = “@default”- Task List id
    • title – optional- new title of the the Task
    • notes-optional- new description of the Task
    • due-optional- new due date of the TaskinRFC 3339 format
    • completed-optional- flag showing whether the Task is completed
  • delete-task– deletes an existing Task
    • id -required- Task id
    • list-optional,default = “@default”- Task List id

 

Share Button
Posted in General Tagged with: ,

Leave a Reply

Your email address will not be published. Required fields are marked *

*