Add support for ingesting etag data from API endpoints

Most of the YouTube API endpoints that return resources expose an etag
property. It is highly desirable for consumers to be able to have
access to this property in order to perform conditional requests (using
If-Match / If-None-Match) or to verify that resources have changed.

Delegate etag to list

Define a singleton method on list that is the list's etag

Set etag instance variable when getting the last response

Collections specs now test for etag support

Revert "Delegate etag to list"

This reverts commit 62fe580.

Add etag method that fetches the etag if not already set
This allows the etag to be fetched for a collection / list response. Example: account.playlists.etag will now return the
etag. Before it would return nil.

Remove exists from singular models and moves it into the resource model

Removes attr_reader and defines an etag method
If the object has an @auth object and an @id then we fetch the etag.
This allows us to fetch the etag for an object like the following:

Yt::Playlist.new(id: youtube_playlist_id, auth: account).etag

Remove counting a collection to force the retrieval of an etag

Update etag specs for video and playlist_items models

Fix missing question mark on nil call

Remove collection.count call in collections / subscriptions and change
fetch_page to fetch_etag

Correct resource name from channel to video

Author: eddorre

lib/yt/actions/list.rb

@@ -12,15 +12,22 @@ def first!
         first.tap{|item| raise Errors::NoItems, error_message unless item}
       end
 
+      def etag
+        @etag ||= fetch_etag
+      end
+
     private
 
       def list
+        owner = self
         @last_index, @page_token = 0, nil
         Enumerator.new(-> {total_results}) do |items|
           while next_item = find_next
             items << next_item
           end
           @where_params = {}
+        end.tap do |enum|
+            enum.define_singleton_method(:etag) { owner.instance_variable_get(:@etag) }
         end
       end
 
@@ -63,7 +70,7 @@ def resource_class
       #   Can be overwritten by subclasses that initialize instance with
       #   a different set of parameters.
       def new_item(data)
-        resource_class.new attributes_for_new_item(data)
+        resource_class.new attributes_for_new_item(data).merge(etag: data['etag'])
       end
 
       # @private
@@ -91,11 +98,17 @@ def eager_load_items_from(items)
 
       def fetch_page(params = {})
         @last_response = list_request(params).run
+        @etag = @last_response.body['etag']
         token = @last_response.body['nextPageToken']
         items = extract_items @last_response.body
         {items: items, token: token}
       end
 
+      def fetch_etag
+        response = list_request(list_params).run
+        response.body['etag']
+      end
+
       def list_request(params = {})
         @list_request = Yt::Request.new(params).tap do |request|
           print "#{request.as_curl}\n" if Yt.configuration.developing?

lib/yt/collections/assets.rb

@@ -17,7 +17,7 @@ def insert(attributes = {})
 
       def new_item(data)
         klass = (data["kind"] == "youtubePartner#assetSnippet") ? Yt::AssetSnippet : Yt::Asset
-        klass.new attributes_for_new_item(data)
+        klass.new attributes_for_new_item(data).merge(etag: data['etag'])
       end
 
       # @return [Hash] the parameters to submit to YouTube to list assets

lib/yt/collections/resources.rb

@@ -19,7 +19,7 @@ def insert(attributes = {}, options = {}) #
     private
 
       def attributes_for_new_item(data)
-        {id: data['id'], snippet: data['snippet'], status: data['status'], auth: @auth}
+        {id: data['id'], snippet: data['snippet'], status: data['status'], auth: @auth, etag: data['etag']}
       end
 
       def resources_params

lib/yt/models/playlist.rb

@@ -209,11 +209,6 @@ def reports_params
         end
       end
 
-      # @private
-      def exists?
-        !@id.nil?
-      end
-
     private
 
       # @see https://developers.google.com/youtube/v3/docs/playlists/update

lib/yt/models/playlist_item.rb

@@ -83,11 +83,6 @@ def video
 
     ### PRIVATE API ###
 
-      # @private
-      def exists?
-        !@id.nil?
-      end
-
       # @private
       # Override Resource's new to set video if the response includes it
       def initialize(options = {})

lib/yt/models/resource.rb

@@ -20,6 +20,19 @@ def id
         end
       end
 
+    ### ETAG ###
+      def etag
+        return nil unless exists?
+
+        @etag ||= fetch_etag
+      end
+
+    ### EXISTS? ###
+
+      def exists?
+        !@id.nil?
+      end
+
     ### STATUS ###
 
       has_one :status
@@ -56,6 +69,7 @@ def initialize(options = {})
           @id = options[:id]
         end
         @auth = options[:auth]
+        @etag = options[:etag]
         @snippet = Snippet.new(data: options[:snippet]) if options[:snippet]
         @status = Status.new(data: options[:status]) if options[:status]
       end
@@ -139,6 +153,20 @@ def fetch_channel_id
         end
       end
 
+      def fetch_etag
+        return nil if @auth.nil? || @id.nil?
+
+        collection = resource_collection.new(auth: @auth).where(id: @id)
+        resource = collection.first
+        resource.etag if resource
+      end
+
+      def resource_collection
+        name = self.class.to_s.demodulize.pluralize
+        require "yt/collections/#{name.underscore}"
+        "Yt::Collections::#{name}".constantize
+      end
+
       # Since YouTube API only returns tags on Videos#list, the memoized
       # `@snippet` is erased if the video was instantiated through Video#search
       # (e.g., by calling account.videos or channel.videos), so that the full

lib/yt/models/video.rb

@@ -635,11 +635,6 @@ def initialize(options = {})
         end
       end
 
-      # @private
-      def exists?
-        !@id.nil?
-      end
-
       # @private
       # Tells `has_reports` to retrieve the reports from YouTube Analytics API
       # either as a Channel or as a Content Owner.

spec/collections/channels_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+require 'yt/collections/channels'
+
+describe Yt::Collections::Channels do
+  subject(:collection) { Yt::Collections::Channels.new }
+
+  describe '#etag' do
+    let(:etag) { 'etag123' }
+
+    before do
+      expect_any_instance_of(Yt::Request).to receive(:run).once do
+        double(body: {'etag'=> etag, 'items'=> [], 'pageInfo'=> {'totalResults'=>0}})
+      end
+    end
+
+    it 'returns the etag from the list response' do
+      expect(collection.etag).to eq etag
+    end
+  end
+end

spec/collections/comment_threads_spec.rb

@@ -43,4 +43,19 @@
       end
     end
   end
+
+  describe '#etag' do
+    let(:parent) { Yt::Video.new id: 'any-id' }
+    let(:etag) { 'etag123' }
+
+    before do
+      expect_any_instance_of(Yt::Request).to receive(:run).once do
+        double(body: {'etag'=> etag, 'items'=> [], 'pageInfo'=> {'totalResults'=>0}})
+      end
+    end
+
+    it 'returns the etag from the list response' do
+      expect(collection.etag).to eq etag
+    end
+  end
 end

spec/collections/playlist_items_spec.rb

@@ -41,4 +41,19 @@
 
     it { expect(collection.delete_all).to eq [true] }
   end
-end
+
+  describe '#etag' do
+    let(:etag) { 'etag123' }
+    let(:behave) { receive(:fetch_etag).and_call_original }
+
+    before do
+      expect_any_instance_of(Yt::Request).to receive(:run).once do
+        double(body: {'etag'=> etag, 'items'=> [], 'pageInfo'=> {'totalResults'=>0}})
+      end
+    end
+
+    it 'returns the etag from the list response' do
+      expect(collection.etag).to eq etag
+    end
+  end
+end