YouTube: Unlocking JavaScript’s Potential with CORS

Web developers are accustomed to making magical user experiences with a few lines of elegant JavaScript, but when faced with talking to RESTful services like the YouTube API, the options have been anything but simple. The most common approach relies on a technique known as JSONP, which relied on dynamically inserting a <script> tag on a page and triggering a local callback function with response from an external service. The YouTube API has supported JSONP for a while now, but developers using this approach are probably familiar with its drawbacks: request failures can lead to the JavaScript callback never being triggered, and JSONP can only be used for read-only API calls that don’t require HTTP request headers being set.

A modern alternative to JSONP is Cross-Origin Resource Sharing (CORS), which allows JavaScript developers to make arbitrary HTTP requests (GETs, PUTs, POSTs, etc.) via the standard XMLHttpRequest interface. Not every browser supports the extensions to XMLHttpRequest that support CORS, but if you’re using one that does we have some good news for you: the gdata.youtube.com web servers that host the YouTube Data API now are enabled for CORS support!

This opens up a whole new class of web application integration with YouTube done purely in client-side JavaScript, without any need for running server-side code. To illustrate what’s now possible, take a look at this sample code. When run in a browser that supports CORS, you can authenticate using OAuth 2 and then perform the entire browser-based upload flow entirely from JavaScript. Previously, the portion of the code that POSTed metadata to the YouTube API needed to be run on a web server.

We can’t wait to see what JavaScript developers will build now that the doors to CORS are open. Enjoy!

Cheers,
—Jeff Posnick, YouTube API Team

Building Professional Video Sites with YouTube APIs

Using video on your website can add greater depth and richness for your audience. However, to do encoding, hosting and streaming right it takes some time and skill. If you’re lacking in either, here are some suggestions for sites that make it easy to help you setup video-based websites.

VidCaster is a video content management system, whose goal is to make building a website with video as easy as possible.

VidCaster makes use of custom URLs, video sitemaps, metadata, and thumbnails to integrate well with search engines. They provide lots of features to customize your video site, like uploading a logo, picking a theme and choosing custom colors, and you can even upload custom CSS. Using their video management interface, you can publish, unpublish and delete videos. VidCaster can even distribute the videos from your video site to third-party sites such as YouTube and Twitter, and they can also integrate analytics from third-party sources.

VidCaster uses OAuth2 with the YouTube API to manage the user’s YouTube account, using both SUP (Simple Update Protocol) and polling to make sure a user’s video site is always in sync with their YouTube channel. Companies that use VidCaster include AirBnB, Hackers and Founders, and Dirtcast.

By integrating closely with YouTube’s data API, VidCaster makes it easy for users to take advantage of YouTube’s video service from within their own custom video site.

Moviecom.tv tries to make it easy for businesses to build video sites about their company.

Like VidCaster, Moviecom.tv provides users with a variety of features to customize their video site. They too show videos hosted on YouTube, but their integration with YouTube doesn’t yet include all the features that VidCaster does — for instance, Moviecom.tv can show YouTube videos using the iframe player, but they haven’t yet integrated with YouTube’s data API. This is something they plan on doing early in 2012. Moviecom.tv also touts their mobile application which takes the friction out of recording and uploading video to the right place.

And they’re doing well at it — they were recently named a Red Herring Global 100 Winner. Internet World, City Index, and Staples are all example sites created using their platform:

Companies like VidCaster and Moviecom.tv are a welcome part of the online video ecosystem. As Moviecom.tv CEO Gillian O’Neil once noted, Moviecom.tv isn’t competing with YouTube. By enabling third-party video sites to embed YouTube videos, YouTube isn’t trying to get a bigger piece of the pie. They’re making the pie bigger.

Cheers,
—Shannon -jj Behrens, YouTube API Team

Introducing Google Account support and YouTube API v2.1

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 presenting an option for the user to link 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 chose 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

YouTube: ClientLogin #FAIL

The YouTube API supports a number of authentication schemes—AuthSub, OAuth 1 and 2, and ClientLogin—but
it’s that last method, ClientLogin, that is in many ways the most
problematic. This blog post will cover some of the ways ClientLogin
attempts can fail, and when possible, provide ways of working around
those failures.

Before
we get into that, though, a bit of a public service announcement: given
all the ways that things can go wrong when using ClientLogin, please
consider using one of the alternative methods of authentication that the
YouTube API supports! AuthSub and in particular OAuth 2 are
straightforward to implement and aren’t susceptible to the issues that
we’ll cover with ClientLogin. Even if you’re writing a small script for
personal use, obtaining one long-lived AuthSub or OAuth 2 token and
reusing that for authentication is preferable to hardcoding a login name
and password for ClientLogin. And just because your code doesn’t have
access to a web browser doesn’t mean that ClientLogin is your only
option—this guide covers techniques for using OAuth 2 in such scenarios.

With that out of the way, let’s investigate some failures!

Scenario 1: A user with an unlinked YouTube account attempts ClientLogin.
This scenario won’t actually lead to a failure as of right now, but it will in the near future. As was recently announced on the main YouTube blog, all YouTube accounts must be linked to a Google Account or else logins will start fail—the current plan is to disable logins for unlinked accounts towards the end of April.
The only workaround is to have your users link their YouTube account to
a Google Account. If they login from a web browser, either at www.youtube.com
or using AuthSub/OAuth, they’ll be taken through the steps to link
accounts. It’s important to note that while we are requiring linked
accounts, we will continue to accept either a YouTube username or a
Google Account email address as the Email parameter in the ClientLogin request.

Scenario 2: A user who has enabled to OpenID federated sign-in attempts ClientLogin.
Federerated sign-in using OpenID
is a new method of authenticating Google Accounts that correspond to
email addresses on specific email providers (currently Yahoo! and AOL).
It is currently being offered on an opt-in basis, so for the time being,
just because someone’s Google Account is associated with an @yahoo.com or @aol.com
address does not mean that they are using Federated sign-in. For the
users who have opted-in, ClientLogin will no longer work at all. With
Federated sign-in, all login requests need to be processed by the
identity provider, and Google’s ClientLogin servers cannot relay the
credentials to a third-party server on the user’s behalf. Because
AuthSub and both versions of OAuth are web-based, users can log in
directly on the identity provider’s site and have that redirect back to
Google’s servers to issue the appropriate AuthSub or OAuth token.
Migrating off of ClientLogin to AuthSub or OAuth is the only way to
provide authentication that works with OpenID accounts.

Scernario 3: A user who has enabled 2-step verification attempts ClientLogin.
This scenario, and the reasons why it will result in a failure, is covered in detail in an earlier blog post. The important takeaway is that a user with 2-step verification enabled needs to generate application-specific passwords
for each application that requires ClientLogin, and provide that
password instead of their normal Google Account password. Alternatively,
using AuthSub or OAuth allows you users to log in using their two
factor credentials directly, leading to a better user experience.

Scenario 4: A user encounters a CAPTCHA when attempting ClientLogin.
This is not a new failure scenario, but it’s often overlooked by developers who don’t properly handle it. The ClientLogin documentation
includes recommendations for how your application should handle CAPTCHA
responses from ClientLogin attempts. If you’re using AuthSub or OAuth,
your application does not need to worry about logic for handling
CAPTCHAs—it’s taken care of for you by the standard AuthSub and OAuth
login process.

This
may seem like an exhaustive list of failure scenarios, but as we
continue to iterate on the login experience for YouTube and Google
Accounts, chances are more “gotchas” will crop up in the future. We’ll
do our best to keep our developer community informed, but the best way
to future-proof your application is to stop using ClientLogin!

—Jeffrey Posnick, YouTube API Team

Staging Server Now Defaults to YouTube API Version 2

The
YouTube Google Data API currently exists in two flavors: version 1 and
version 2. If you’re not explicitly requesting version 2 of the API,
then you’re using the default, version 1.

As we add new functionality to the API, it’s invariably added to version 2: features like partial responses/updates, extended access controls, captioning support, and YouTube Insight statistics are
only available to developers accessing the newer release. We’ve kept
version 1 running as-is for a while now, and will continue to do so for
months to come, but we’re taking the first step to transition
developers off of version 1 of the API by changing the default in our
staging server environment to version 2.

We
expect to default the production environment to version 2 before the
end of the year, and we will post again when we have more definite
dates. In the meantime, if you are still using version 1 of the API,
please prepare for the change by taking one of the following steps:

  • Modify a test version of your code to access stage.gdata.youtube.com URLs as described in this blog post. You’ll automatically default to version 2, and you can test and make changes to your code against the staging server.
  • Start explicitly requesting version 2 using the v=2 URL parameter or GData-Version HTTP request header.
    Most of the YouTube API client libraries provide methods for switching
    between API versions, and they will take care of setting the
    appropriate
    GData-Version header for you. You may need to modify your code to make it compatible with version 2.
  • If
    you know that your code is incompatible with version 2 of the YouTube
    API and you can’t fix things yet, start explicitly requesting version 1
    of the API. Note that this is not a long-term solution, as all code
    will eventually need to be migrated off of version 1.

Stay
tuned over the coming months for more announcements about the change to
the default in production, and the eventual decommission of version 1,
currently scheduled for October 2011.

Cheers,
-Jeff Posnick, YouTube API Team