Getting started using Google APIs: Workspace & OAuth client IDs (1/3)

Introduction

Are you a developer but a complete beginner using Google APIs? This series is for you because I'm showing you how get started from scratch. Each API family differs from others, so while it would be great if the UX (user experience) was completely consistent across all APIs, this isn't the case, so my goal is to help developers understand how their use differs between product families. As mentioned in the previous post, I'm starting with the Google Workspace (formerly called G Suite and Google Apps) APIs.

Google Workspace ("GWS") refers to the collection of: Gmail, Google Drive, Calendar, Docs, Sheets, Slides, Forms, plus others. Behind each of these well-known apps is a RESTful API. Why GWS APIs first? The main reason is they're completely free (up to certain limits) and do not require a credit card. Don't worry though... we'll get to other Google APIs soon thereafter, including: Cloud ("GCP"), Google Maps, YouTube, Firebase, etc., and more interesting, demo apps using APIs from different product families.

Regardless of which Google APIs you use, there are two main requirements:

1. Authentication — typically login & password; using Google APIs requires a Google account
2. Authorization — an application needs permission to call an API & perform data access

A third item you should use is a "client library." While optional, their use is strongly recommended, and I'll cover this topic in the next post. Authentication and authorization are commonly abbreviated as "authn" and "authz", respectively. Because both are long, similar words that start with, "auth," some think they're the same thing, but alas, they're not. Check out this page in the official docs to help differentiate. I'll do the same below as well as guide you to creating the required resources.

Authentication ("authn") — get a Google account

Authn refers to user identity, typically achieved with a login and password. More secure forms of authn include responding to a smartphone prompt or providing a biometric such as a fingerprint or retina scan. While a Google account is required to use Google APIs, it doesn't have to be a Gmail account; Google accounts can be based on an existing email address. Having a Gmail account is only convenient because it combines the two, giving you both a personal email and a Google account, in a single entity.

Another kind of Google account is a Workspace account. You get one when your company or school chooses Workspace as its office productivity suite. I don't recommend these types of accounts because it is very likely your school or company administrator has disabled developer projects because of billing or security concerns. So just stick with a Gmail or personal Google account.

Action item(s)

1. Create a new Google account (or select an existing account). Per my earlier remark, you can create an account with a Gmail address or without Gmail using your personal email address. Once you're logged into your new or existing Google account, you're done with authn.

Authorization ("authz") — create a Google developer project and relevant credentials

Credentials give your app the authorization to access a Google API. Google APIs support three credentials types. Which you use depends on who owns the data that an API accesses, as shown in the following table:

Credential type	Data accessed by API	Example Google API families
API key	Public data	Maps APIs
OAuth client ID	Data owned by (human) users	GWS APIs
Service account	Data owned by apps/projects	GCP APIs

 

1. API keys — used for APIs that access public data, e.g., looking for places on Google Maps, sending a picture to the GCP Vision API, searching YouTube for videos, and so on. Because all Maps APIs access public data, expect to only use API keys.
2. OAuth client IDs — used for APIs that access data owned by (human) users. Your app needs a user's permission to access their documents on Drive, their messages in Gmail, videos in a user's YouTube playlists, and so on. Since Workspace data is almost always personal data, expect to use OAuth client IDs with GWS APIs.
3. Service accounts — used for APIs that access data owned by an app or project. For cloud-based apps, there's no human to prompt for permissions, plus the data isn't owned by humans anyway. Authorization is implicitly granted via service account public/private keypairs created with specific permissions. As you can also guess, this means GCP APIs typically require service accounts.

As mentioned in the previous post, I'm starting with GWS APIs first, meaning using OAuth client IDs. Future posts will cover Google APIs that use either API keys or service accounts. From the above, while it may seem APIs only accept one type of credentials, note that some Google APIs accept more than one type.

For example, while the Cloud Vision API typically expects service accounts, it may also work with API keys or OAuth client IDs. I created a sample app featuring the Vision API where it used OAuth client IDs for authz — my justification being that the app also uses the Drive and Sheets APIs. It's already tricky enough using multiple Google APIs much less using multiple credentials types too.

OPTIONAL: Complete experience via "codelab"

In the section below, I offlink several times to a tutorial (a "Google codelab") I wrote a few years ago introducing developers to coding with GWS APIs. Codelabs are self-paced, hands-on tutorials that lead you step-by-step in accomplishing a task and/or learning a Google API or API feature. Rather than regurgitating the exact same content in these posts, I'll point to specific sections to review or execute.

The codelab consolidates the content from these (three) posts and implements a Python script that isplays the first 100 files or folders in a user's Google Drive. We'll eventually end up there, but some of you may learn better/faster by doing an end-to-end, immersive project, in which case, feel free to do the entire codelab at http://g.co/codelabs/gsuite-apis-intro. (If interested, all Google codelabs can be accessed at http://g.co/codelabs.)

Now let's set up your project and allocate credentials for your app. If you're new to Google APIs, a project is the logical container for an application and its resources, and all API usage requires a project. Once you have a project, you need to create credentials for API access. Before executing the instructions below, review this page and this one in the official docs to get an idea of what you'll be doing because we're pretty much going to follow the steps outlined in those docs.

Action item(s)

1. Go to the Developer Console ("DevConsole") at https://console.developers.google.com and sign into your Google account. See the sidebar below if you have multiple Google accounts.
2. At the top of the DevConsole, create a new project (look for buttons labeled New Project or Create Project), or select an existing project. Specific instructions on project setup can be found in the codelab.
3. Click on the Credentials tab in the left-nav to get to the credentials page listing all credentials for your project. Now click Create credentials at the top and select OAuth client ID. For Application type, select Desktop app. This and following steps are also detailed in the codelab as well as the docs pages listed at the end of the previous section.
4. OAuth client IDs need a name, so take the default or create something meaningful like, "Google API demo".
5. You may be prompted to create an OAuth consent screen; do so and select an External app. You only need to provide basic info like app name, email address, etc. Since we're only building a prototype, this info will only be exposed to you as the test user of your script. To learn more about this, see the OAuth consent screen documentation.
6. After the client ID has been created, you'll be prompted to download a JSON credentials file. Rather than a super long default filename like, client_secret_SOME-GIANT-HASH.googleusercontent.com, save it with a shorter name, e.g., client_secret.json or client_id.json. With an active project and downloaded JSON credentials file, your authz tasks are complete.

TIP: More than one Google account?

If you have more than one Google account, select the avatar in the upper-right corner to confirm you're using the desired account. If not, select the correct one in the avatar dialog. When you have multiple Google accounts, an authenticated user ("auth user") number helps your browser differentiate between those users in any Google service URL. This number shows up in the URL in one of these two formats: 1) ...&authuser=N&... or 2) .../u/N/.... In both cases, N is the auth user number, starting at 0 (default) and incrementing for each account.

As a convenience, you can add this HTTP field to most Google URLs to select which of your Google accounts to use. For example, use the following URL to access the DevConsole as auth user #2: console.developers.google.com?authuser=2.

What's next?

Congrats! You've completed the first step in using Google APIs. Note there was no Python, Node.js, or any language-specific steps today; the process you completed is language-agnostic and API-agnostic, meaning you can use any Google API accepting OAuth client IDs as its authz mechanism, meaning an API that accesses user-owned data. In the next post, you will be taking more language- and API-dependent steps:

1. Enable GWS APIs you wish to use
2. Install client library for GWS APIs

For those who prefer more visual content, below is a video I made years ago covering much of what's in this post and giving you a preview of the next one. The video's screenshots are outdated now but the functionality has mostly remained the same. Until the next post!

NEXT POST: Part 2/3 on working with GWS APIs

---

WESLEY CHUN, MSCS, is a Google Developer Expert (GDE) in Google Cloud (GCP) & Google Workspace (GWS), author of Prentice Hall's bestselling "Core Python" series, co-author of "Python Web Development with Django", and has written for Linux Journal & CNET. He runs CyberWeb specializing in GCP & GWS APIs and serverless platforms, Python & App Engine migrations, and Python training & engineering. Wesley was one of the original Yahoo!Mail engineers and spent 13+ years on various Google product teams, speaking on behalf of their APIs, producing sample apps, codelabs, and videos for serverless migration and GWS developers. He holds degrees in Computer Science, Mathematics, and Music from the University of California, is a Fellow of the Python Software Foundation, and loves to travel to meet developers worldwide at conferences, user group events, and universities. Follow he/him @wescpy & his technical blog. Find this content useful? Contact CyberWeb if you may need help or buy him a coffee (or tea)!