Introducing Google Account support and YouTube API v2.1

Update (December 2011): The YouTube API now supports associating an unlinked Google Account with a YouTube channel as well as providing username suggestions. 

Authenticated access to YouTube APIs lets your app offer many features that are unavailable to logged-out users. By authenticating user actions, your app can allow users to manage subscriptions, create playlists, and upload videos. Until recently, users could only perform any of these operations if they had YouTube accounts. (A YouTube account provides a user with a YouTube channel.)

We are pleased to announce that we have also started to give Google Account holders who don’t already have YouTube channels access to certain YouTube features on YouTube.com and in the YouTube API. We call these unlinked Google Accounts since they haven’t already been linked to a YouTube channel. For example, a user with a Gmail account or an Android device is certain to have a Google Account but may not have already linked that account to a YouTube channel.

What this means for your application is that with a few relatively simple changes, you should be able to allow authenticated access for users who have unlinked Google Accounts. Thus, those users will be able to log in to YouTube without having to create a YouTube username.

In a moment, we’ll dive into the details of how to use the API with unlinked Google Accounts and also offer a few user experience recommendations for your YouTube API application. First, though, a quick note about the new minor YouTube API revision that we’re introducing. 

Say "Hello!" to YouTube API v2.1

When designing this feature, we decided to take a conservative approach toward backward compatibility. The set of write operations supported for Google Accounts is currently a subset of API operations available to YouTube account holders. Rather than expose existing applications to accounts with potentially restricted functionality, we’re explicitly requiring that an application prepared to handle unlinked Google Accounts tells us so by using the API version 2.1, a new, minor version of the API. Our documentation explains that you can specify an API version by appending v=2.1 to the API request URI or by using the GData-Version: 2.1 request header. 

HTTP response codes for authenticated operations

API v2.0 supports all authenticated operations for users with YouTube accounts, which could also be called linked Google Accounts, but doesn’t support any authenticated operations for unlinked Google Accounts. If the authentication token for a v2.0 API request identifies an unlinked Google Account, the API will return a 401 NoLinkedYouTubeAccount error.

In API v2.1, however, a number of operations that require authentication are supported for users with unlinked Google Accounts, and the API will return a 200 response code for those operations. For operations that aren’t supported for unlinked Google Accounts in v2.1, the API will return an HTTP 403 Forbidden error with a youtube_signup_required error code. 

The table below shows how API v2.1 changes response codes when different types of users try to execute operations that require authentication:

	API v2	API v2.1
YouTube Account	200 OK	200 OK
Unlinked Google Account	401 NoLinkedYouTubeAccount	200 OK or 403 Forbidden youtube_signup_required

Handling the youtube_signup_required error

We do not recommend that you try to modify your application to provide a different experience for users with YouTube accounts than for unlinked Google Accounts. That approach would require you to constantly update your application as YouTube expands the list of features that we support for unlinked Google Accounts.

Instead, we recommend that you prepare your application to gracefully handle the youtube_signup_required error, preferably by associating the unlinked Google Account with a YouTube channel using the API, or presenting an option for the user to navigate to https://www.youtube.com/create_channel. If you are building a mobile application, you can bypass a redirect by using https://m.youtube.com/create_channel instead. The API documentation lists the operations that are and are not currently supported for unlinked Google Account holders.

The XML below shows a sample youtube_signup_required error:

<errors> 
  <error>
    <domain>yt:service</domain>
    <code>youtube_signup_required</code> 
  </error>
</errors>

User profiles for unlinked Google Account holders

A user profile entry for a user with an unlinked Google Account differs from a user profile entry for a user with a YouTube account in two ways:

• An entry for an unlinked Google Account holder contains a <yt:incomplete> tag. (This tag is not present if the user already has a YouTube channel.) It is useful if you choose to disregard our advice about the youtube_signup_required error and modify your application to provide a different user experience for users with unlinked Google Accounts.
• An entry for an unlinked Google Account holder contains only a few tags as those users can not customize their profile data without first creating a YouTube channel. The <entry> tag definition lists the different tags that may appear in a profile entry depending on whether the user has a YouTube account or an unlinked Google Account.

Displaying an email address for unlinked Google Account holders

In addition to handling the youtube_signup_required error, your application should also be prepared to display an email address for users with unlinked Google Accounts.

In Closing

If you have reached this point in the blog post, thanks for being a dedicated reader. We recognize that unlinked Google Accounts do introduce a certain level of complexity, but, at the same time, they can also open your application to a much larger audience of users who use Google services but haven’t created YouTube channels yet.

We also want to note that v2.1 does not deprecate v2.0 since it is a minor revision. Going forward, new features unrelated to unlinked Google Accounts will be added to both v2.0 and v2.1 but not to the (deprecated) v1.0 of the API. 

Version 2.1 of the API is now available for testing on stage.gdata.youtube.com, and will be released to production in mid-October. 

Cheers, 

—Jarek Wilkiewicz, YouTube API Team