gds-api-adapters 4.1.3 → 4.2.0

data/lib/gds_api/content_api.rb

@@ -1,19 +1,20 @@
 require_relative 'base'
 require_relative 'exceptions'
+require 'gds_api/content_api/list_response'
 
 class GdsApi::ContentApi < GdsApi::Base
   include GdsApi::ExceptionHandling
 
   def sections
-    get_json!("#{base_url}/tags.json?type=section")
+    get_list!("#{base_url}/tags.json?type=section")
   end
 
   def root_sections
-    get_json!("#{base_url}/tags.json?type=section&root_sections=true")
+    get_list!("#{base_url}/tags.json?type=section&root_sections=true")
   end
 
   def sub_sections(parent_tag)
-    get_json!("#{base_url}/tags.json?type=section&parent_id=#{CGI.escape(parent_tag)}")
+    get_list!("#{base_url}/tags.json?type=section&parent_id=#{CGI.escape(parent_tag)}")
   end
 
   def tag(tag)
@@ -21,22 +22,22 @@ class GdsApi::ContentApi < GdsApi::Base
   end
 
   def with_tag(tag)
-    get_json!("#{base_url}/with_tag.json?tag=#{CGI.escape(tag)}&include_children=1")
+    get_list!("#{base_url}/with_tag.json?tag=#{CGI.escape(tag)}&include_children=1")
   end
 
   def curated_list(tag)
-    get_json("#{base_url}/with_tag.json?tag=#{CGI.escape(tag)}&sort=curated")
+    get_list("#{base_url}/with_tag.json?tag=#{CGI.escape(tag)}&sort=curated")
   end
 
   def sorted_by(tag, sort_by)
-    get_json!("#{base_url}/with_tag.json?tag=#{CGI.escape(tag)}&sort=#{sort_by}")
+    get_list!("#{base_url}/with_tag.json?tag=#{CGI.escape(tag)}&sort=#{sort_by}")
   end
 
   def artefact(slug, params={})
     edition = params[:edition]
     snac = params[:snac]
 
-    url = "#{base_url}/#{slug}.json"
+    url = "#{base_url}/#{CGI.escape(slug)}.json"
     query = params.map { |k,v| "#{k}=#{v}" }
     if query.any?
       url += "?#{query.join("&")}"
@@ -84,6 +85,14 @@ class GdsApi::ContentApi < GdsApi::Base
     get_batch(last_batch_url, response)
   end
 
+  def get_list!(url)
+    get_json!(url) { |r| ListResponse.new(r, self) }
+  end
+
+  def get_list(url)
+    get_json(url) { |r| ListResponse.new(r, self) }
+  end
+
   private
     def base_url
       endpoint

data/lib/gds_api/content_api/list_response.rb

@@ -0,0 +1,90 @@
+require "json"
+require "gds_api/response"
+require "link_header"
+
+class GdsApi::ContentApi < GdsApi::Base
+
+  # Response class for lists of multiple items from the content API.
+  #
+  # These responses are in a common format, with the list of results contained
+  # under the `results` key. The response may also have previous and subsequent
+  # pages, indicated by entries in the response's `Link` header.
+  class ListResponse < GdsApi::Response
+
+    # The ListResponse is instantiated with a reference back to the API client,
+    # so it can make requests for the subsequent pages
+    def initialize(response, api_client)
+      super(response)
+      @api_client = api_client
+    end
+
+    # Pass calls to `self.each` to the `results` sub-object, so we can iterate
+    # over the response directly
+    def_delegator :results, :each
+
+    def has_next_page?
+      ! page_link("next").nil?
+    end
+
+    def next_page
+      # This shouldn't be a performance problem, since the cache will generally
+      # avoid us making multiple requests for the same page, but we shouldn't
+      # allow the data to change once it's already been loaded, so long as we
+      # retain a reference to any one page in the sequence
+      @next_page ||= if has_next_page?
+        @api_client.get_list! page_link("next").href
+      else
+        nil
+      end
+    end
+
+    def has_previous_page?
+      ! page_link("previous").nil?
+    end
+
+    def previous_page
+      # See the note in `next_page` for why this is memoised
+      @previous_page ||= if has_previous_page?
+        @api_client.get_list! page_link("previous").href
+      else
+        nil
+      end
+    end
+
+    # Transparently get all results across all pages. Compare this with #each
+    # or #results which only iterate over the current page.
+    #
+    # Example:
+    #
+    #   list_response.with_subsequent_pages.each do |result|
+    #     ...
+    #   end
+    #
+    # or:
+    #
+    #   list_response.with_subsequent_pages.count
+    #
+    # Pages of results are fetched on demand. When iterating, that means
+    # fetching pages as results from the current page are exhausted. If you
+    # invoke a method such as #count, this method will fetch all pages at that
+    # point. Note that the responses are stored so subsequent pages will not be
+    # loaded multiple times.
+    def with_subsequent_pages
+      Enumerator.new { |yielder|
+        self.each do |i| yielder << i end
+        if has_next_page?
+          next_page.with_subsequent_pages.each do |i| yielder << i end
+        end
+      }
+    end
+
+  private
+    def link_header
+      @link_header ||= LinkHeader.parse @net_http_response["Link"]
+    end
+
+    def page_link(rel)
+      link_header.find_link(["rel", rel])
+    end
+  end
+end

data/lib/gds_api/json_client.rb

@@ -40,32 +40,28 @@ module GdsApi
       do_raw_request(Net::HTTP::Get, url)
     end
 
-    def get_json(url)
-      ignoring GdsApi::HTTPNotFound do
-        get_json! url
+    # Define "safe" methods for each supported HTTP method
+    #
+    # Each "bang method" tries to make a request, but raises an exception if
+    # the response is not successful. These methods discard those exceptions
+    # and return nil.
+    [:get, :post, :put, :delete].each do |http_method|
+      method_name = "#{http_method}_json"
+      define_method method_name do |url, *args|
+        ignoring GdsApi::HTTPNotFound do
+          send (method_name + "!"), url, *args
+        end
       end
     end
 
-    def get_json!(url)
-      @cache[url] ||= do_json_request(Net::HTTP::Get, url)
-    end
-
-    def post_json(url, params)
-      ignoring GdsApi::HTTPNotFound do
-        post_json! url, params
-      end
+    def get_json!(url, &create_response)
+      @cache[url] ||= do_json_request(Net::HTTP::Get, url, nil, &create_response)
     end
 
     def post_json!(url, params)
       do_json_request(Net::HTTP::Post, url, params)
     end
 
-    def put_json(url, params)
-      ignoring GdsApi::HTTPNotFound do
-        put_json! url, params
-      end
-    end
-
     def put_json!(url, params)
       do_json_request(Net::HTTP::Put, url, params)
     end
@@ -80,12 +76,21 @@ module GdsApi
       response.body
     end
 
-    def do_json_request(method_class, url, params = nil)
+    # method_class: the Net::HTTP class to use, e.g. Net::HTTP::Get
+    # url:    the request URL
+    # params: the data to send (JSON-serialised) in the request body
+    # create_response: optional block to instantiate a custom response object
+    #                  from the Net::HTTPResponse
+    def do_json_request(method_class, url, params = nil, &create_response)
+
       response, loggable = do_request(method_class, url, params)
 
+      # If no custom response is given, just instantiate Response
+      create_response ||= Proc.new { |r| Response.new(r) }
+
       if response.is_a?(Net::HTTPSuccess)
         logger.info loggable.merge(status: 'success', end_time: Time.now.to_f).to_json
-        Response.new(response)
+        create_response.call(response)
       elsif response.is_a?(Net::HTTPNotFound)
         raise GdsApi::HTTPNotFound.new(response.code.to_i)
       else

data/lib/gds_api/test_helpers/content_api.rb

@@ -135,7 +135,7 @@ module GdsApi
         singular_response_base.merge(
           "title" => titleize_slug(slug),
           "format" => "guide",
-          "id" => "#{CONTENT_API_ENDPOINT}/#{slug}.json",
+          "id" => "#{CONTENT_API_ENDPOINT}/#{CGI.escape(slug)}.json",
           "web_url" => "http://frontend.test.gov.uk/#{slug}",
           "details" => {
             "need_id" => "1234",

data/lib/gds_api/test_helpers/content_api/artefact_stub.rb

@@ -41,7 +41,7 @@ module GdsApi
         
         private
           def url_without_query
-            "#{CONTENT_API_ENDPOINT}/#{slug}.json"
+            "#{CONTENT_API_ENDPOINT}/#{CGI.escape(slug)}.json"
           end
 
           # Ensure that all keys and values are strings 
@@ -54,4 +54,4 @@ module GdsApi
       end
     end
   end
-end
+end

data/lib/gds_api/version.rb

@@ -1,3 +1,3 @@
 module GdsApi
-  VERSION = '4.1.3'
+  VERSION = '4.2.0'
 end

data/test/content_api_test.rb

@@ -14,8 +14,94 @@ describe GdsApi::ContentApi do
     it "should show a list of sections" do
       content_api_has_root_sections(["crime"])
       response = @api.sections
+
+      # Old-style dictionary access
       first_section = response["results"][0]
       assert_equal "#{@base_api_url}/tags/crime.json", first_section["id"]
+
+      # Also check attribute access
+      first_section = response.first
+      assert_equal "#{@base_api_url}/tags/crime.json", first_section.id
+    end
+
+    def section_page_url(page_parameter)
+      if page_parameter
+        "#{GdsApi::TestHelpers::ContentApi::CONTENT_API_ENDPOINT}/tags.json?type=section&page=#{page_parameter}"
+      else
+        "#{GdsApi::TestHelpers::ContentApi::CONTENT_API_ENDPOINT}/tags.json?type=section"
+      end
+    end
+
+    def stub_section_page(page_parameter, options)
+      total_pages = options.fetch :of
+
+      url = section_page_url(page_parameter)
+
+      page_number = page_parameter || 1
+      # e.g. page 2 -> 11..20
+      range_start = (page_number - 1) * 10 + 1
+      range_end = page_number * 10
+      tags = (range_start..range_end).map { |number|
+        tag_for_slug("section-#{number}", "section")
+      }
+      body = plural_response_base.merge(
+        "results" => tags
+      )
+
+      links = []
+      if page_number > 1
+        links << "<#{section_page_url(page_number - 1)}>; rel=\"previous\""
+      end
+      if page_number < total_pages
+        links << "<#{section_page_url(page_number + 1)}>; rel=\"next\""
+      end
+
+      stub_request(:get, url).to_return(
+        status: 200,
+        body: body.to_json,
+        headers: {"Link" => links.join(",")}
+      )
+    end
+
+    it "should allow iteration across pages" do
+      [nil, 2].each do |page_parameter|
+        stub_section_page(page_parameter, of: 2)
+      end
+
+      sections = @api.sections
+      assert_equal 20, sections.with_subsequent_pages.count
+      assert_equal "Section 20", sections.with_subsequent_pages.to_a.last.title
+    end
+
+    it "should iterate across three or more pages" do
+      [nil, 2, 3].each do |page_parameter|
+        stub_section_page(page_parameter, of: 3)
+      end
+
+      sections = @api.sections
+      assert_equal 30, sections.with_subsequent_pages.count
+      assert_equal "Section 30", sections.with_subsequent_pages.to_a.last.title
+    end
+
+    it "should not load a page multiple times" do
+      [nil, 2].each do |page_parameter|
+        stub_section_page(page_parameter, of: 2)
+      end
+
+      sections = @api.sections
+
+      3.times do
+        # Loop through all the items, just to make sure we load all the pages
+        sections.with_subsequent_pages.each do end
+      end
+
+      assert_requested :get, section_page_url(2), times: 1
+    end
+
+    it "should display a single page of sections" do
+      stub_section_page(nil, of: 1)
+      sections = @api.sections
+      assert_equal 10, sections.with_subsequent_pages.count
     end
   end
 
@@ -39,6 +125,13 @@ describe GdsApi::ContentApi do
         @api.artefact("devolution-uk", edition: 3)
       end
     end
+
+    it "should be able to fetch artefacts with a '/' in the slug" do
+      content_api_has_an_artefact("travel-advice/aruba")
+      response = @api.artefact("travel-advice/aruba")
+      assert_requested(:get, "#{@base_api_url}/travel-advice%2Faruba.json")
+      assert_equal "#{@base_api_url}/travel-advice%2Faruba.json", response["id"]
+    end
   end
 
   describe "tags" do
@@ -50,8 +143,13 @@ describe GdsApi::ContentApi do
       }.to_json
       stub_request(:get, api_url).to_return(:status => 200, :body => json)
       response = @api.with_tag("crime-and-justice")
+
+      # Old dictionary-style access
       subsection = response["results"][0]
       assert_equal "Complain about a claims company", subsection["title"]
+
+      # Attribute access
+      assert_equal "Complain about a claims company", response.first.title
     end
 
     it "should return tag tree for a specific tag" do

metadata

@@ -2,7 +2,7 @@
 name: gds-api-adapters
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 4.1.3
+  version: 4.2.0
 platform: ruby
 authors: 
 - James Stewart
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-11-28 00:00:00 Z
+date: 2013-01-16 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: plek
@@ -35,8 +35,19 @@ dependencies:
   prerelease: false
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: lrucache
+  name: link_header
   requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :runtime
+  prerelease: false
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: lrucache
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -44,10 +55,10 @@ dependencies:
         version: 0.1.1
   type: :runtime
   prerelease: false
-  version_requirements: *id003
+  version_requirements: *id004
 - !ruby/object:Gem::Dependency 
   name: rdoc
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - "="
@@ -55,10 +66,10 @@ dependencies:
         version: "3.12"
   type: :development
   prerelease: false
-  version_requirements: *id004
+  version_requirements: *id005
 - !ruby/object:Gem::Dependency 
   name: rake
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -66,10 +77,10 @@ dependencies:
         version: 0.9.2.2
   type: :development
   prerelease: false
-  version_requirements: *id005
+  version_requirements: *id006
 - !ruby/object:Gem::Dependency 
   name: webmock
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  requirement: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -77,10 +88,10 @@ dependencies:
         version: "1.8"
   type: :development
   prerelease: false
-  version_requirements: *id006
+  version_requirements: *id007
 - !ruby/object:Gem::Dependency 
   name: mocha
-  requirement: &id007 !ruby/object:Gem::Requirement 
+  requirement: &id008 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -88,10 +99,10 @@ dependencies:
         version: 0.12.4
   type: :development
   prerelease: false
-  version_requirements: *id007
+  version_requirements: *id008
 - !ruby/object:Gem::Dependency 
   name: minitest
-  requirement: &id008 !ruby/object:Gem::Requirement 
+  requirement: &id009 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -99,10 +110,10 @@ dependencies:
         version: 3.4.0
   type: :development
   prerelease: false
-  version_requirements: *id008
+  version_requirements: *id009
 - !ruby/object:Gem::Dependency 
   name: rack
-  requirement: &id009 !ruby/object:Gem::Requirement 
+  requirement: &id010 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -110,10 +121,10 @@ dependencies:
         version: "0"
   type: :development
   prerelease: false
-  version_requirements: *id009
+  version_requirements: *id010
 - !ruby/object:Gem::Dependency 
   name: simplecov
-  requirement: &id010 !ruby/object:Gem::Requirement 
+  requirement: &id011 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -121,10 +132,10 @@ dependencies:
         version: 0.5.4
   type: :development
   prerelease: false
-  version_requirements: *id010
+  version_requirements: *id011
 - !ruby/object:Gem::Dependency 
   name: simplecov-rcov
-  requirement: &id011 !ruby/object:Gem::Requirement 
+  requirement: &id012 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
@@ -132,10 +143,10 @@ dependencies:
         version: "0"
   type: :development
   prerelease: false
-  version_requirements: *id011
+  version_requirements: *id012
 - !ruby/object:Gem::Dependency 
   name: gem_publisher
-  requirement: &id012 !ruby/object:Gem::Requirement 
+  requirement: &id013 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -143,10 +154,10 @@ dependencies:
         version: 1.1.1
   type: :development
   prerelease: false
-  version_requirements: *id012
+  version_requirements: *id013
 - !ruby/object:Gem::Dependency 
   name: timecop
-  requirement: &id013 !ruby/object:Gem::Requirement 
+  requirement: &id014 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -154,8 +165,8 @@ dependencies:
         version: 0.5.1
   type: :development
   prerelease: false
-  version_requirements: *id013
-description: A set of adapters providing easy access to the GDS gov.uk APIs
+  version_requirements: *id014
+description: A set of adapters providing easy access to the GDS GOV.UK APIs
 email: 
 - jystewart@gmail.com
 executables: []
@@ -166,41 +177,41 @@ extra_rdoc_files: []
 
 files: 
 - lib/gds_api/version.rb
-- lib/gds_api/publisher.rb
+- lib/gds_api/base.rb
+- lib/gds_api/licence_application.rb
 - lib/gds_api/panopticon/registerer.rb
-- lib/gds_api/typhoeus_client.rb
-- lib/gds_api/content_api.rb
+- lib/gds_api/needotron.rb
 - lib/gds_api/imminence.rb
-- lib/gds_api/test_helpers/publisher.rb
-- lib/gds_api/test_helpers/content_api.rb
-- lib/gds_api/test_helpers/imminence.rb
+- lib/gds_api/rummager.rb
+- lib/gds_api/content_api.rb
+- lib/gds_api/exceptions.rb
+- lib/gds_api/json_client.rb
+- lib/gds_api/core-ext/openstruct.rb
+- lib/gds_api/response.rb
+- lib/gds_api/content_api/list_response.rb
+- lib/gds_api/publisher.rb
 - lib/gds_api/test_helpers/licence_application.rb
+- lib/gds_api/test_helpers/imminence.rb
+- lib/gds_api/test_helpers/content_api.rb
 - lib/gds_api/test_helpers/content_api/artefact_stub.rb
+- lib/gds_api/test_helpers/publisher.rb
 - lib/gds_api/test_helpers/panopticon.rb
 - lib/gds_api/test_helpers/json_client_helper.rb
-- lib/gds_api/licence_application.rb
-- lib/gds_api/base.rb
-- lib/gds_api/json_client.rb
-- lib/gds_api/response.rb
-- lib/gds_api/rummager.rb
-- lib/gds_api/panopticon.rb
-- lib/gds_api/core-ext/openstruct.rb
 - lib/gds_api/part_methods.rb
-- lib/gds_api/needotron.rb
-- lib/gds_api/exceptions.rb
+- lib/gds_api/panopticon.rb
 - lib/gds_api/helpers.rb
 - README.md
 - Rakefile
-- test/panopticon_api_test.rb
-- test/publisher_api_test.rb
 - test/rummager_test.rb
+- test/publisher_api_test.rb
+- test/licence_application_api_test.rb
+- test/panopticon_api_test.rb
 - test/imminence_api_test.rb
-- test/panopticon_registerer_test.rb
-- test/content_api_test.rb
 - test/json_client_test.rb
-- test/gds_api_base_test.rb
-- test/licence_application_api_test.rb
 - test/test_helper.rb
+- test/gds_api_base_test.rb
+- test/content_api_test.rb
+- test/panopticon_registerer_test.rb
 homepage: http://github.com/alphagov/gds-api-adapters
 licenses: []
 
@@ -214,7 +225,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 306816274510639352
+      hash: -1781835164135696191
       segments: 
       - 0
       version: "0"
@@ -223,7 +234,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 306816274510639352
+      hash: -1781835164135696191
       segments: 
       - 0
       version: "0"
@@ -235,13 +246,13 @@ signing_key:
 specification_version: 3
 summary: Adapters to work with GDS APIs
 test_files: 
-- test/panopticon_api_test.rb
-- test/publisher_api_test.rb
 - test/rummager_test.rb
+- test/publisher_api_test.rb
+- test/licence_application_api_test.rb
+- test/panopticon_api_test.rb
 - test/imminence_api_test.rb
-- test/panopticon_registerer_test.rb
-- test/content_api_test.rb
 - test/json_client_test.rb
-- test/gds_api_base_test.rb
-- test/licence_application_api_test.rb
 - test/test_helper.rb
+- test/gds_api_base_test.rb
+- test/content_api_test.rb
+- test/panopticon_registerer_test.rb

data/lib/gds_api/typhoeus_client.rb

@@ -1,3 +0,0 @@
-require_relative 'response'
-require_relative 'exceptions'
-require_relative 'version'