Hey everybody.
This is Jeff Posnick from the YouTube Developer Relations
team.
And we're continuing a series of videos
about the migration between the older legacy
version of the YouTube data API v2
onto the newer version of the data API v3.
We strongly encourage folks to begin that migration process,
if you haven't done so yet.
And we wanted to highlight certain types of functionality
and talk about the v2 way of doing things,
and how you would go and do the same sort of thing in v3.
We're going to start by talking about how you would actually
get a list of videos that are in a given channel using v3,
the data API.
Folks familiar with v2 the data API
know that you do this pretty much with a single RESTful API
call.
You look for the user upload's feed for a given channel,
and you get back a list of videos by default in an XML
format, although you could also ask for it JSON format
if you want.
In v3, it involves a slightly different set of operations.
And it's just keeping with the overall philosophy with v3
in that you return a very specific set of information
for a specific API call, rather than
returning a lot of information.
So it's a little bit more of a focused API.
And the other main difference is that in v3, we work primarily
with channel IDs rather than legacy usernames.
So if you're familiar with the more v2 way of doing things,
where every channel had a legacy username,
you need to start thinking about channel IDs instead.
And this is particularly important because moving
forward, not every channel does have a legacy username.
So if you did want to uniquely identify any given channel,
there are going to be those channels that
don't have the legacy usernames, and you
do need to get comfortable working with channel IDs.
So let's actually walk through the steps
of doing the operation of getting
the uploads in a channel using version 3 of the API.
And we're going to switch now to a screen
share of that I have up.
And what I have open here is the Google APIs Explorer.
This is a great resource for playing around
with version 3 of the data API or using our analytics API,
or any other of the modern Google APIs.
And it gives you a way of making API calls
within the context of this nice browser web form
in trying out different parameters.
So when you are actually writing code
for using this sort of thing in your own applications,
you're probably going to want to use your client libraries.
But this is a neutral, agnostic way
of showing off the API calls.
So that being said, there are two different steps
for getting the uploads in a given channel,
assuming that you know-- and we're
going to assume right now that we know that channel's legacy
username.
The first step is to get back the playlist ID that
corresponds to the uploads for that channel.
And the way we do that is by making a YouTube.channels.list
call.
And we have that open here in the API Explorer.
And when making version 3 API calls,
pretty much the convention that all the list operations follow
is that you have one parameter called Parts.
And you set this to a value that is a little bit
dependent upon the given method.
And in this particular case, the YouTube
channels that list takes these values over here
in the documentation.
We can describe exactly what all of them do.
And what we want is the content details part.
So instead of returning every single piece of information
that we know about the channel in every API response,
which could get very bloated, you
have to explicitly state what kind of information
you want to get back.
And you get a nice really compact API response back.
So we're going to say we want the content details part back,
and this is how we get the uploads playlist ID.
And there's this parameter called forUsername.
As the documentation states, it lets you pass in a legacy
YouTube username, assuming that the channel that you're
interested in has one.
And it will return information corresponding to that channel.
So this is like a shortcut of getting information
about a channel or looking up a channel's ID, if all you know
is the legacy username.
So in this particular case, we're
going to look up the Google Developers channel.
That's a legacy username.
And we're going to scroll down a bit.
We don't need any of these other fields right now.
And click Execute, and it's making the API call for us.
You'll see these are the parameters.
This is the actual RESTful URL that's being requested.
And you get back this JSON response.
And you'll see over here, because we're only
asking for information about one specific channel,
the item's return array only has one element, not surprisingly.
You do you get this channel ID right here.
If we did want to use that information later on,
that might be useful.
But in the particular context of what we're doing here,
we want the uploads playlist ID.
So I'm going to just copy that.
If you were writing real code, you would obviously
save it to a local variable and use it in a follow-up call.
And I'm going to now make another API call--
and just open up a new tab for that.
And this is going to be a YouTube playlist items list.
And again, the thing to keep in mind
is that in version 3 of the API, many things
are considered playlists.
Instead of, in version 2, where you would go and get
specifically the uploads feed corresponding to a given
channel, in version 3, you first look up
the playlist that corresponds to the uploads for the channel.
And then you do the standard YouTube playlist items
list call.
And this is the same API call that you
would use if you were getting information
about a user-generated playlist.
It's really quite equivalent.
So you'll see that a lot in version 3 of the API,
where we reuse methods or overload the function
of methods so that they could be used
for a variety of different operations.
So in this particular case, we have this part parameter again.
I'm going to pass in the value snippet here.
And snippet is a part that contains
the most relevant information about any given response
item, things that would be useful if you were to,
for instance, want to display information
about the response like in a web browser.
So it'll contain the title for each item,
it'll contain a thumbnail, it'll contain a description.
And that's the type of information
that we want about all the uploads in a given channel.
So I am going to take that copied playlist ID,
and I'm going to paste it into the playlist ID field.
This is something to really keep in mind.
You want this in the playlist ID parameter.
There's a separate parameter called ID.
And that takes in something that's
different than the playlist ID.
So please-- this is a common source of confusion--
make sure that you're setting the playlist ID
parameter in this particular case.
And I'm also going to set max results to 50.
One of the things you'll notice is
that Mac's results is, by default, set
to five in version 3 of the API, which is fine
if you are going to be displaying the results on a web
page, and you don't want a really, really,
long list of videos.
But in this particular case, I want
to get information about as many as I could in a single API
call.
And the most you could get back is 50.
I'm going to click Execute at this point.
And you scroll down, and you'll see this items array
similar to what we saw for the previous one.
But in this case, the items array has multiple items in it,
because there are, not surprisingly,
quite a few uploads in the Google Developers channel.
You'll have information about when that upload was published,
and titles, descriptions, thumbnails,
things I mentioned before.
One other thing that I wanted to point out
is the way paging works in version 3 of the API,
because this is something that's different than version 2
as well.
So previously in version 2, you could
pass in whatever you wanted as the start index.
And that would allow you to jump to different places
within something like an upload's feed.
In version 3 of the API, we don't
take in a start index parameter.
We take in what's known as a paging token.
And that gets returned in the API response.
And it's used when you build up your next request,
as a way of saying, hey, you know
I've gotten this page of results.
Give me the next page of results.
This allows for certain efficiencies on the server,
and it means that you get a more reliable paging experience when
you're using version 3.
It just allows things to be a little bit more efficient,
and it means that less likely to be duplicates or things that
are unordered.
So let's actually take in that next page token value
from this response.
And we're going to construct the next page of requests
by pasting it in here.
So we're going to have all the same parameters,
but we're sending page token now.
And if I click Execute, things should return back.
But in this particular case, I get a different set of results.
This is basically results 51 through 100.
And we can continue doing that.
Basically as long as there's a next page token returned,
that means that there is another page of results
that you could get back.
And you could loop, more or less,
until you stop getting back next page tokens.
As soon as that stops being returned,
you know that you've reached the end of the list.
So hopefully that's a good overview
for how you would do something in version 2,
and then how you would do the v3 equivalent.
Stay tuned for future shows.
They cover more topics in version 3 of the API.
And thanks so much for joining us.
Again, I'm Jeff Posnick from the Developer Relations team.
And stay tuned.
Cheers.