Steps to make a Google API call

This short summary of steps to prepare and realize a Google API call is based on invoking the Google Calendar API, but other segments should be quite similar.

[1] Manual preparation (one-time).

[1a] Sign in to Google.

This is the starting point. You need to be signed in to approach Google APIs.

[1b] Create a project.

Navigate to GDC (Google Development Console) at https://console.developers.google.com/project. "Create new project".

[1c] Enable the API you are going to invoke.

Go to GDC > APIs & Auth > APIs, scroll down and "enable" your API.

[1d] Create new Client ID.

(We assume here that we need to access private data; accessing public data would be simpler - no client ID but a simple API key would be used, but this is not subject to this study).

GDC > Credentials > Create new OAuth Client ID > ... Edit the Client ID adding https://localhost to the 'Authorized JavaScript origins' and 'Authorized redirect URIs' sections.

Now you see the 'Client ID for native application' data: CLIENT ID, CLIENT SECRET, REDIRECT URIs.

[1e] Optionally export OAuth basic data (to have it at hand for the coming actions).

GDC > Credentials > Download JSON.

The output will be something like this:

{
    "installed": {
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "client_secret": "4i1................",
        "token_uri": "https://accounts.google.com/o/oauth2/token",
        "client_email": "",
        "redirect_uris": ["urn:ietf:wg:oauth:2.0:oob", "oob"],
        "client_x509_cert_url": "",
        "client_id": "506................apps.googleusercontent.com",
        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs"
    }
}

Now have a short rest before starting with the programmatic calls to follow.

[2] Get OAuth code, refresh token and access token (one-time).

[2a] Get OAuth code.

• Open a browser and navigate to

https://accounts.google.com/o/oauth2/auth?response_type=code&redirect_uri=https://localhost&scope=https://www.googleapis.com/auth/calendar&client_id=your_client_id&access_type=offline&prompt=consent

where your_client_id is the CLIENT ID from 'GDC > APIs & Auth > Credentials' (or the client_id taken from the earlier exported json),
• Sign in when asked to do so,
• Press the 'Accept' button on the newly opened page requesting your consent for your product (as entered earlier on the 'GDC > APIs & Auth > Consent screen') to access or manage your calendar,
• Watch the address bar - now you have received your OAuth code as part of the URL like this:

https://localhost/?code=4/4/cVwJ35................

(As far as above URL starts with 'localhost' page content does not matter, never mind even if showing some error.)

Store the code (without the possible # trailer) for using it with next actions. (This code can be further used only once, but you can freely browse for a new code when needed.)

[2b] Get refresh token and access token.

Now an HTTP POST request has to be sent. Following sample is based on the popular Fiddler Composer, but you may prefer to use cURL or help yourself with a HTML form or a javascript/jQuery request.

POST https://accounts.google.com/o/oauth2/token HTTP/1.1
Content-type: application/x-www-form-urlencoded

grant_type=authorization_code&code=your_oauth_code&client_id=your_client_id&client_secret=your_client_secret&redirect_uri=https://localhost

where your_auth_code is the above received OAuth code, your_client_id is the CLIENT ID from 'GDC > APIs & Auth > Credentials' (or the client_id taken from the earlier exported json) and your_client_secret is the CLIENT SECRET from 'GDC > APIs & Auth > Credentials' (or the client_secret taken from the earlier exported json).

NOTE that grant_type is the FIRST parameter in the list.
NOTE that the OAuth code can be used only once, so, you will have to navigate each time for a new OAuth code, as explained earlier, if current POST request fails for any reason.

Well, your goal is to get an HTTP 200 response code. The response content will be something like:

{
    "access_token" : "ya29.1................",
    "token_type" : "Bearer",
    "expires_in" : 3600,
    "refresh_token" : "1/Oauh................"
}

Here are the desired refresh token and access token (without the quotes). Note and keep save especially the refresh code. The refresh code will be used each time when starting a new API call, where an access token is needed and the short living access code has meanwhile expired.

[3] Make the API call.

[3a] Get new access token (unless your latest access token has not yet expired).

Again an HTTP POST request has to be sent. Following sample is based on the popular Fiddler Composer, but you may prefer to use cURL or help yourself with a HTML form or a javascript/jQuery request.

POST https://www.googleapis.com/oauth2/v3/token HTTP/1.1
Content-type: application/x-www-form-urlencoded

client_id=your_client_id&client_secret=your_client_secret&refresh_token=your_refresh_token&grant_type=refresh_token

where your_client_id is the CLIENT ID from 'GDC > APIs & Auth > Credentials' (or the client_id taken from the earlier exported json), your_client_secret is the CLIENT SECRET from 'GDC > APIs & Auth > Credentials' (or the client_secret taken from the earlier exported json) and your_refresh_token is the refresh_token (without the quotes) received as a result of the previous post request.

The response content will be something like:

{
    "access_token": "ya29.1................",
    "token_type": "Bearer",
    "expires_in": "3600"
}

We have a fresh access token and can finally make the API calls.

[3b] Call that Google API (Google Calendar API in this case):

We make HTTP GET requests. As earlier stated, the samples are based on the popular Fiddler Composer, but you may prefer to use cURL or help yourself with a HTML form or a javascript/jQuery request.

Sample 1: Get your calendars list.

GET https://www.googleapis.com/calendar/v3/users/me/calendarList HTTP/1.1
Authorization: Bearer your_access_token

where your_access_token is above access_token (without the quotes).

We get a JSON response bearing a list of the various calendars for the Google profile in question, where we can get info about the calendar name/summary, calendar ID etc. The calendar ID is specifically important, because we need it for the call for the single calendar entries list.

Sample 2: Get single calendar entries list.

GET https://www.googleapis.com/calendar/v3/calendars/your_calendar_id/events HTTP/1.1
Authorization: Bearer your_access_token

where your_calendar_id is the calendar ID got from the results of the previous API call, requesting calendars list, and your_access_token is above access_token (without the quotes).

We now have certain calendar properties and a list of the calendar events with indications about name, start date, default reminders, override reminders, visibility, web address etc. Of course, there are very many filtering arguments you can add to your request - read more in the relevant API reference online.

That's it. Not easy the first time, but efforts are paying off later - you have a stable and easy fine-grained access to the universe of Google data.