HTTPCaller and Google Calendar API: GET

Introduction

In this exercise, we will use the HTTPCaller with the Google Calendar API to demonstrate the practical application of several HTTP methods (GET, POST, PUT, PATCH, DELETE). Google Calendar’s REST API uses HTTP as their transfer protocol to view, edit or modify your calendar objects like events, reminders, custom calendars, and invitations. 

In the following exercise, we will set out a FME Workbench workspace and ensure a connection to the Google Calendar API. After establishing a connection, we will use a GET request to query information about our calendars. Before getting started, make sure you're familiar principles of HTTP requests and responses.
 

Requirements

• A free Google email account

Part 1: Authorization

HTTPCaller does not require authentication to make a request. But unless the server (API) is open and requires no authentication, the call is unlikely to be successful. Authentication is required by many servers to access their resources. 

There are many different types of HTTP authentication schemes, so it’s best to always start by first consulting the documentation. Since we’re using Google Calendar’s API, the documentation specifies using 0Auth 2.0 to authorize requests. 


To get full use of Google APIs, there is a process for obtaining credentials that requires registration and consent to their terms of service. Consult the terms of service prior to using the Google Calendar API for your projects. 

For the purposes of this demonstration, we can authenticate using FME Workbench’s Web Connections . Google Calendar API 0Auth 2.0 is included as a preconfigured web service accessible from the FME Options > Web Connections menu. All that is required is a Google account to sign in. In addition to the Calendar API, there are other Google API services available in Workbench or follow a tutorial for connecting to Google+ (and other OAuth 2.0 schemes) in FME Workbench. 

In addition to Google’s API, there are many more Web Services shipped with FME Desktop, available for download from the FME Hub, or explore connecting to your own Web Services.  

1. Start a Workspace
Open up FME Workbench and start with a blank workspace. Add a Creator transformer to your canvas by clicking on the canvas and typing “Creator”. Since our data source will be from the web, there is no need to use a reader. The Creator kickstarts the workflow by creating features we can write to downstream. Every call we make during this exercise will begin with a Creator. Next, add and connect an HTTPCaller transformer. 

2. Make a Web Connection 
Open Web Connections from the FME Options menu and select the “+” button below the listed Connections.  

Mac: FME Workbench > Preferences... > Web Connections
Windows: Tools > FME Options...



Select Google Calendar as the Web Service and give the connection a name. 



Select Authenticate… and in the pop up window, log in with your Google account. 

The Google Calendar Web Connection will now appear in the Connections list. Select OK to finish.



3. Authenticate the HTTPCaller
With Google Calendar registered as a Web Services, we can use the Web Connection option to authenticate all of our requests with the HTTPCaller. 

Back on the canvas, double-click the HTTPCaller or select the cog wheel to review its parameters. Near the bottom, there is an option to Use Authentication. Enable Use Authentication then expand the option using the dropdown arrow to the left of the parameter.  



Select Web Connection as the Authentication Method and choose the Google Calendar Web Connection. 

Part 2: Making Requests

Equipped with a web connection, we can begin making requests. But before requesting to make any changes to a server, it is good practice to have an understanding of the data you will be working with. 

Since we are working with Google Calendar, we have the opportunity to visualize the data we will be accessing and editing. Open a browser and log into your Google account to access the calendar application from the waffle menu. Optionally, you can access your calendar by going to calendar.google.com. 

Depending on your account, it might be full of events, or (mostly) empty like this one. On the side bar, there is a list of personal or imported calendars. Throughout each day, there are the events and reminders associated with those calendars. While it is possible to edit, modify and view this information from the UI, there are plenty of reasons to use HTTP requests to do the same actions. You might want to automate an event, sync other applications with your calendar, build an app that uses Google’s API, set up alerts, run automations, or any number of actions, each which can be done with the HTTPCaller. 



The “HTTP Methods” calendar will be used to demonstrate making requests by creating, updating, and deleting requests. Create a similar one for testing (select the “+” sign next to Other calendars) or use one of your pre-existing calendars. 
 

GET: List the Calendars

Instead of viewing calendars in a browser, we can view and edit the same information from the Google Calendar API. GET functions to request a representation of the resource specified. They are the most frequently used HTTP request. GET should be designed to be idempotent and safe, so repeated use of the request will not affect the server state. However, it’s always worthwhile consulting the specific documentation to the API you are using, because some are designed differently.
 

A GET request to a server oftentimes returns a response body from the server containing the requested information. To begin, let’s use a simple GET request to request a list of Calendars associated with our Google accounts. 

1. Consult the documentation. 
You’re likely to encounter a GET request when using just about any API. GET functions to retrieve a representation of a resource from a server. In its most simple form, a GET request consists of just a Uniform Resource Location (URL) and method. These also happen to be the only required parameters to use the HTTPCaller.

To demonstrate our first call, we will use a GET request to fetch a list of calendars associated with our Google account. CalendarList: list provides the URL and method required to make the call. Copy the Request URL to your clipboard, we will use it in the HTTPCaller in the next step. 



2. Build the Request
Back in your workspace, open the HTTPCaller to build the request. Enter the copied URL in the Request URL parameter. Select GET as the HTTP Method. Remember to select Use Authentication and choose your Google Calendar connection, we will use it for every call. While  the rest of the parameters can be left default, note that the response body is saved to an Attribute named _response_body.



3. Run the Workspace. 
With Feature Caching enabled, run the workspace and open up the Visual Preview table by clicking on the green magnifying glass on the HTTPCaller. The API’s response is stored in the _response_body attribute and the status code is stored in the _http_status_code attribute. The 200 status code lets us know the HTTP Request was successfully received by the server. 



Double click to open up the _response_body to see the API response. The server has returned a JSON body with a list of calendar objects and their attributes, including the “HTTP Methods” calendar we observed in the GUI. Copy the “id” value for a calendar you’d like to use for the next request. 



4. Interpreting a JSON Response Body. 
To easily interpret response messages in a workspace, attach a JSONFragmentor to your HTTPCaller. Instead of navigating a large response body, isolate fragments with JSON queries. Here I am using the “items” key to divide the response body into feature types containing json objects. Keep in mind that the JSON Query may need to be modified for each call, depending on how the JSON response body is structured. 



Now, you can view your response as individual feature types. 

GET: List Calendar Events

Let's use another GET request to retrieve a list of events associated with the calendar, this time using path and query parameters to refine our request. First, let's go over some facts about building URLs. 

Path parameters follow the URL domain name to refine the resource location. Query parameters are used to filter or sort the resource. The key is listed, followed by an equals sign and its value. They are separated from the rest of the URL by a question mark. Multiple queries, for example when submitting a web form, are separated by an ampersand (&) sign. URL encoding is used to include special characters (such a space). For example, spaces are replaced by %20. 

Here is an example of a GET request format with path and query parameters: 

With the HTTPCaller, the process of building a URL is simplified. The URL, query parameters, and special formatting are each handled by the transformer’s graphical interface. 



Let's try it out by making another GET request. This time we will fetch all of the events associated with our calendar and sort them by when they were last updated. 

1. Consult the documentation.
Navigate to the Events: list reference page. In addition to the method and URL, it includes descriptions and data types of both path and query parameters. The path parameter (calendarId) is shown as pink italics in the URL, it tells the server we want to perform an action on the resource (calendar, in this case) specified here. 



2. Build the Request
To make a new GET request in FME Workbench, modify your last HTTPCaller or add another Creator and HTTPCaller to the same workspace. Ensure any new HTTPCallers are using authentication. 

Copy the path to the Request URL field on the HTTPCaller. Replace the calendarId path parameter with the “id” we copied from the previous request. 



With only these two parameters, it is possible to make the call. The HTTP response would be a list of all the events associated with that calendar. But let's say we want to sort the returned event objects, to do this we can use the orderBy query parameter. The parameter name is "orderBy", its data type is a string, and its value can be “startTime” or “updated”. We’ll sort the events by the last update. 



A traditional request URL with the path and query parameters would look something like this: 

GET https://www.googleapis.com/calendar/v3/calendars/lmni1lebfff4hkqq0lii5c6m2g@group.calendar.google.com/events?orderBy=updated

The HTTPCaller lets you easily add and organize request parameters using the transformer interface. Enter path parameters in the Request URL and use the Query String Parameters section for query parameters. Directly enter parameters or use the Text Editor to build them dynamically with attribute values. Here is the same GET request built in the HTTPCaller: 



3. Run the Workspace
With the URL, method, and parameters fulfilled, run the workspace to the HTTPCaller (or JSONFragmentor, if you choose) and view the response. Returned is a list of that calendar’s events and their attributes, sorted by the last time update timestamp. 



Similarly, viewed with the JSONFragmentor. 

You'll notice the response returns the same basic information that is visible when accessing your calendar from a web browser. In addition, there is additional information (like an Id, creation data, etc.) that will help you build your own workflows with the API. Keep reading the next tutorial to learn how to use POST, PUT, PATCH, and DELETE methods with the Google Calendar API and HTTPCaller. 

Data Attribution

The data used here originates from data made available by Google Calendar API . Please review the terms of service and usage limits before using the API in your projects.