figshare_api_v2 0.9.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3b830ddd5bc2ff58ce03dc8c96f2029fe21e7913c9ce360cd09078b19c446277
+  data.tar.gz: 682588604c24ee90a212f854815e4da68edb68f33230d7d4d019b8dd3ed50b8e
+SHA512:
+  metadata.gz: bf62ed1ab2f35779259c09c0beee9c04d1b0caa7a06d5186de7c2d9d4010e4bcf4c24af83c06215d512e35ff9e63bd4318b3a412fc64b5c369d93465835ccc03
+  data.tar.gz: fde9f1ee7a1d052e25553175412d813d9ffc7dca198d05c715693e9d7601ef14cc84ba6b1976416a61a90ac052ab220e9b268db4895c4f87306c3027cbf0539c

data/History.txt

@@ -0,0 +1,58 @@
+robertburrowes	Thu Nov 5 11:09:37 2020 +1300
+	bump version
+robertburrowes	Thu Nov 5 11:09:10 2020 +1300
+	bump version
+robertburrowes	Thu Nov 5 11:08:53 2020 +1300
+	Upload test of directory
+robertburrowes	Thu Nov 5 11:08:30 2020 +1300
+	Trying real world examples
+robertburrowes	Thu Nov 5 11:08:02 2020 +1300
+	dependency on WIKK::dir_r gem
+robertburrowes	Thu Nov 5 11:07:41 2020 +1300
+	Fixes, after tests. Added upload_dir
+robertburrowes	Fri Oct 30 15:07:02 2020 +1300
+	playing with more tests
+robertburrowes	Fri Oct 30 15:06:45 2020 +1300
+	minor tidy up. This version successfully uploaded files
+robertburrowes	Fri Oct 30 15:05:32 2020 +1300
+	check response content type, and only parse json, when json
+robertburrowes	Fri Oct 30 09:41:42 2020 +1300
+	More testing
+robertburrowes	Fri Oct 30 09:41:31 2020 +1300
+	Added trace code to upload.
+robertburrowes	Fri Oct 30 09:40:43 2020 +1300
+	Name conflict with delete. Use explicit name
+robertburrowes	Fri Oct 30 09:39:36 2020 +1300
+	Ignore test data
+robertburrowes	Fri Oct 30 09:06:18 2020 +1300
+	Init class test
+robertburrowes	Fri Oct 30 09:05:27 2020 +1300
+	Init class test
+robertburrowes	Fri Oct 30 09:05:17 2020 +1300
+	Example code
+robertburrowes	Fri Oct 30 09:05:03 2020 +1300
+	include the OAI PMH stub
+robertburrowes	Fri Oct 30 09:04:47 2020 +1300
+	Changed to use Figshare::Base calls
+robertburrowes	Fri Oct 30 09:03:58 2020 +1300
+	Stub for Stats class
+robertburrowes	Fri Oct 30 09:03:42 2020 +1300
+	stub for OAI PMH class
+robertburrowes	Fri Oct 30 09:03:22 2020 +1300
+	comment aligned with Init class initialize
+robertburrowes	Fri Oct 30 09:03:00 2020 +1300
+	Added an Init class to dynamically create subclasses
+robertburrowes	Thu Oct 29 19:23:55 2020 +1300
+	playing with tests
+robertburrowes	Thu Oct 29 19:23:40 2020 +1300
+	Update
+robertburrowes	Thu Oct 29 19:23:29 2020 +1300
+	Added in missing api calls
+robertburrowes	Thu Oct 29 18:13:47 2020 +1300
+	mode change only
+robertburrowes	Thu Oct 29 17:59:56 2020 +1300
+	Changes to build files to get first pkg created
+robertburrowes	Thu Oct 29 17:32:27 2020 +1300
+	initial version. Not tested yet
+Rob Burrowes	Mon Oct 19 09:52:15 2020 +1300
+	Initial commit

data/Manifest.txt

@@ -0,0 +1,18 @@
+History.txt
+Manifest.txt
+README.md
+Rakefile
+lib/authors.rb
+lib/base.rb
+lib/figshare_api_v2.rb
+lib/institutions.rb
+lib/oai_pmh.rb
+lib/other.rb
+lib/private_articles.rb
+lib/private_collections.rb
+lib/private_projects.rb
+lib/public_articles.rb
+lib/public_collections.rb
+lib/public_projects.rb
+lib/stats.rb
+lib/upload.rb

data/README.md

@@ -0,0 +1,74 @@
+# figshare_api_v2
+
+* Docs :: https://UoA-eResearch.github.io/figshare_api_v2/
+* Source :: https://github.com/UoA-eResearch/figshare_api_v2
+* Gem :: https://rubygems.org/gems/figshare_api_v2
+* Figshare :: https://docs.figshare.com/
+
+## DESCRIPTION:
+
+Figshare version 2 API. 
+
+## FEATURES/PROBLEMS:
+
+* Stats API not implemented.
+* oai pmh api not implemented.
+* Need to build a test suite
+* impersonate option, for PrivateArticles, PrivateCollections and PrivateProjects ignored for DELETE, and non-json POST and PUT.
+
+## SYNOPSIS:
+
+```
+require 'figshare_api_v2'
+
+# Either initialize once, and call @figshare.authors.x @figshare.institutions.x, ...
+@figshare = Figshare::Init.new(figshare_user: 'figshare_admin', conf_dir: "#{__dir__}/conf")
+
+@figshare.authors.detail(author_id: 12345) { |a| puts a }
+@figshare.institutions.private_articles { |article| puts article }
+#...
+
+# Or initialize each class individually
+@authors = Figshare::Authors.new(figshare_user: 'figshare_admin', conf_dir: "#{__dir__}/conf")
+@institutions = Figshare::Institutions.new(figshare_user: 'figshare_admin', conf_dir: "#{__dir__}/conf")
+
+@authors.detail(author_id: 12345) { |a| puts a }
+@institutions.private_articles { |article| puts article }
+
+#...
+````
+
+## REQUIREMENTS:
+
+* depends on 'wikk_webbrowser' gem
+* depends on 'wikk_json' gem (beware: adds to_j to the base classes)
+
+## INSTALL:
+
+* sudo gem install figshare_api_v2
+
+## LICENSE:
+
+The MIT License
+
+Copyright (c) 2020
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

data/Rakefile

@@ -0,0 +1,31 @@
+# -*- ruby -*-
+require 'rubygems'
+require 'hoe'
+Hoe.plugin :yard
+load "#{__dir__}/version"
+
+Hoe.spec PROJECT do 
+  self.readme_file = "README.md"
+  self.developer( "Rob Burrowes","r.burrowes@auckland.ac.nz")
+  remote_rdoc_dir = '' # Release to root
+  
+  self.yard_title = PROJECT
+  self.yard_options = ['--markup', 'markdown', '--protected']
+
+  self.dependency "wikk_json", "~> 0.1.2"
+  self.dependency "wikk_webbrowser", "~> 0.9.0"
+  self.dependency "dir_r", "~> 1.0.0"
+end
+
+
+#Validate manfest.txt
+#rake check_manifest
+
+#Local checking. Creates pkg/
+#rake gem
+
+#create doc/
+#rake docs  
+
+#Copy up to rubygem.org
+#rake release VERSION=1.0.1

data/lib/authors.rb

@@ -0,0 +1,41 @@
+module Figshare
+  # Figshare Author APIs
+  #
+  class Authors < Base
+    # Search authors
+    #
+    # @param institution [Boolean] Just our institution
+    # @param group_id [Integer] Only return this group's collections
+    # @param orcid [String] Matches this orcid
+    # @param is_active [Boolean]
+    # @param is_public [Boolean]
+    # @param order [String] "published_date" Default, "modified_date", "views", "cites", "shares"
+    # @param order_direction [String] "desc" Default, "asc"
+    # @yield [Hash] {id, first_name, last_name, full_name, url_name, is_active, is_public, orcid_id, institution_id, group_id, job_title}
+    def search(institute: false, group_id: nil, orcid: nil,
+                is_active: true, is_public: true,  
+                order: 'published_date', order_direction: 'desc',
+                search_for:,
+                &block
+              )
+      args = { 'search_for' => search_for }
+      args['institution'] = @institute_id if ! institute.nil?
+      args['group_id'] = group_id if ! group_id.nil?
+      args['is_active'] = is_active if ! is_active.nil?
+      args['is_public'] = is_public if ! is_public.nil?
+      args['orcid'] = orcid if ! orcid.nil?
+      args['order'] = order if ! order.nil?
+      args['order_direction'] = order_direction if ! order_direction.nil?
+      post(api_query: 'account/authors/search', args: args, &block)
+    end
+    
+    # Get an authors details
+    #
+    # @param author_id [Integer] Figshare Author ID
+    # @yield [Hash] {id, first_name, last_name, full_name, url_name, is_active, is_public, orcid_id, institution_id, group_id, job_title}
+    def detail(author_id:, &block)
+      get(api_query: "account/authors/#{author_id}",  &block)
+    end
+  end
+
+end

data/lib/base.rb

@@ -0,0 +1,262 @@
+module Figshare
+  require "wikk_webbrowser"
+  require "wikk_json"
+  require 'Time'
+  
+  # Supporting web calls to the API
+  #
+  class Base
+    attr_accessor :auth_token
+    attr_accessor :base_dir
+    attr_accessor :article_index_file
+    attr_accessor :hostname
+    attr_accessor :api_url
+    attr_accessor :institute_id
+  
+    # Init reads the Json configuration files, setting @course_codes_to_faculty and @academic_department_code_to_faculty
+    # Opens a connection to the LDAP server, setting @ldap for other methods to use.
+    #
+    # @param figshare_user [String] figshare user, in the figshare_keys.json
+    # @param conf_dir [String] directory for figshare_keys.json and figshare_site_params.json
+    def initialize(figshare_user:, conf_dir:)
+      figshare_token = load_json_file("#{conf_dir}/figshare_keys.json")
+      @auth_token = figshare_token[figshare_user]
+    
+      figshare_site_params = load_json_file("#{conf_dir}/figshare_site_params.json")
+    
+      @hostname = figshare_site_params['host']
+      @api_url = figshare_site_params['api_url']
+      @institute_id = figshare_site_params['institute_id']
+    end
+  
+    # Parse the config file
+    #
+    # @param filename [String] config file name to parse
+    # @return [Hash|Array] parsed json configuration file.
+    private def load_json_file(filename)
+      JSON.parse(File.read(filename))
+    end
+  
+    # get iterates through the API response, yielding each value to the passed block
+    # When Figshare API usually has no paging option.
+    # If there is no block, then the results are printed (useful for debugging)
+    #
+    # @param api_query [String] base figshare api call, to which we add parameters defined in args
+    # @param args [Hash] Key, value pairs which get converted to ?key=arg&key=arg...
+    # @param debug [Boolean] print result to stdout
+    # @yield [String] if given a block, iterates through the result from figshare
+    # @return [Integer] number of results.
+    private def get(api_query:, args: {}, debug: false, &block)
+      content_type = response = nil
+      WIKK::WebBrowser.https_session( host: @hostname, verify_cert: false ) do |ws|
+        response = ws.get_page( query: "#{@api_url}#{api_query}",
+                                authorization: "token #{@auth_token}",
+                                form_values: args
+                              )
+        content_type = ws.header_value(key: 'Content-Type')
+      end
+      return iterate_json_response(response: response, content_type: content_type, debug: debug, &block)
+    end
+
+    # get_paginate iterates through the API response, yielding each value to the passed block, fetching new pages ,as needed.
+    # Figshare API usually has the option of page and page_size parameters, to help with large downloads.
+    # If there is no block, then the results are printed (useful for debugging)
+    #
+    # @param api_query [String] base figshare api call, to which we add parameters defined in args
+    # @param args [Hash] Key, value pairs which get converted to ?key=arg&key=arg...
+    # @param debug [Boolean] print result to stdout
+    # @param by_offset [Boolean] use offset/limit rather than page/page_size in API calls
+    # @yield [String] if given a block, iterates through the result from figshare
+    # @return [Integer] number of results.
+    private def get_paginate(api_query:, args: {}, debug: false, by_offset: false, &block)
+      args = {} if args.nil?
+      if ! args.is_a?(Hash)
+      raise "get_paginate(): Expecting args to be a Hash"
+      end
+ 
+      offset = 0
+      page = 1
+      limit = page_size = 100
+      result_count = 0
+      loop do
+        content_type = response = nil
+        form_args = by_offset ? {"limit"=>limit, "offset"=>offset} : {"page_size"=>page_size, "page"=>page}
+        WIKK::WebBrowser.https_session( host: @hostname, verify_cert: false ) do |ws|
+          response = ws.get_page( query: "#{@api_url}#{api_query}",
+                                  authorization: "token #{@auth_token}",
+                                  form_values: form_args.merge(args)
+                                )
+          content_type = ws.header_value(key: 'Content-Type')
+        end
+        page_count = iterate_json_response(response: response, content_type: content_type, debug: debug, &block)
+        result_count += page_count
+        break if page_count < page_size # Got less results than we asked for, so it was the last page
+
+        page += 1 #Ready to fetch next page
+        offset += limit #if we use offset, then mor
+      end
+      
+      return result_count
+    end
+
+    # post iterates through the API response, yielding each value to the passed block
+    # When Figshare API usually has no paging option.
+    # If there is no block, then the results are printed (useful for debugging)
+    #
+    # @param api_query [String] base figshare api call, to which we add parameters defined in args
+    # @param args [Hash] Key, value pairs which get converted to ?key=arg&key=arg...
+    # @param debug [Boolean] print result to stdout
+    # @param content_type [String] Assuming Json, but might need binary ('application/octet-stream')
+    # @yield [String] if given a block, iterates through the result from figshare
+    # @return [Integer] number of results.
+    private def post(api_query:, args: {}, data: nil, debug: false, content_type: 'application/json; charset=UTF-8', &block)      
+      body = nil
+      if data.is_a?(Hash)
+        # Convert hash to json, and merge in additional args
+        body = data.merge(args).to_j
+      elsif data.nil? && ! args.empty?
+        # No data, but args, so just use the args
+        body = args.to_j
+      else
+        # Data isn't a Hash, so just pass it through (might be nil)
+        body = data
+      end
+      
+      content_type = response = nil
+      WIKK::WebBrowser.https_session( host: @hostname, verify_cert: false ) do |ws|
+        response = ws.post_page(  query: "#{@api_url}#{api_query}",
+                                  content_type: content_type,
+                                  authorization: "token #{@auth_token}",
+                                  data: body
+                              )
+        content_type = ws.header_value(key: 'Content-Type')
+      end
+      return iterate_json_response(response: response, content_type: content_type, debug: debug, &block)
+    end
+
+    # post_paginate iterates through the API response, yielding each value to the passed block, fetching new pages ,as needed.
+    # Figshare API usually has the option of page and page_size parameters, to help with large downloads.
+    # If there is no block, then the results are printed (useful for debugging)
+    #
+    # @param api_query [String] base figshare api call, to which we add parameters defined in args
+    # @param args [Hash] Key, value pairs which get converted to ?key=arg&key=arg...
+    # @param debug [Boolean] print result to stdout
+    # @param by_offset [Boolean] use offset/limit rather than page/page_size in API calls
+    # @yield [String] if given a block, iterates through the result from figshare
+    # @return [Integer] number of results.
+    private def post_paginate(api_query:, args: {}, debug: false, by_offset: false,  &block)
+      page = 1
+      offset = 0
+      limit = page_size = 100
+      result_count = 0
+      
+      args = {} if args.nil?
+      if ! args.is_a?(Hash)
+       raise "post_paginate(): Expecting args to be a Hash"
+      end
+      
+      loop do
+        content_type = response = nil
+        form_args = by_offset ? {"limit"=>limit, "offset"=>offset} : {"page_size"=>page_size, "page"=>page}
+        WIKK::WebBrowser.https_session( host: @hostname, verify_cert: false ) do |ws|
+          response = ws.post_page(  query: "#{@api_url}#{api_query}",
+                                    content_type: 'application/json; charset=UTF-8',
+                                    authorization: "token #{@auth_token}",
+                                    data: args.merge(form_args).to_j
+                                  )
+          content_type = ws.header_value(key: 'Content-Type')
+        end
+        page_count = iterate_json_response(response: response, content_type: content_type, debug: debug, &block)
+        result_count += page_count
+        break if page_count < page_size # Got less results than we asked for, so it was the last page
+
+        page += 1 #Ready to fetch next page
+        offset += limit #if we use offset
+      end
+      return result_count
+    end
+
+    # put iterates through the API response, yielding each value to the passed block
+    # When Figshare API usually has no paging option.
+    # If there is no block, then the results are printed (useful for debugging)
+    #
+    # @param api_query [String] base figshare api call, to which we add parameters defined in args
+    # @param args [Hash] Key, value pairs which get converted to ?key=arg&key=arg...
+    # @param debug [Boolean] print result to stdout
+    # @param content_type [String] Assuming Json, but might need binary ('application/octet-stream')
+    # @yield [String] if given a block, iterates through the result from figshare
+    # @return [Integer] number of results 
+    private def put(api_query:, args: {}, data: nil, debug: false, content_type: 'application/json; charset=UTF-8', &block)
+      body = nil
+      if data.is_a?(Hash)
+        # Convert hash to json, and merge in additional args
+        body = data.merge(args).to_j
+      elsif data.nil? && ! args.empty?
+        # No data, but args, so just use the args
+        body = args.to_j
+      else
+        # Data isn't a Hash, so just pass it through (might be nil)
+        body = data
+      end
+
+      content_type = response = nil
+      WIKK::WebBrowser.https_session( host: @hostname, verify_cert: false ) do |ws|
+        response = ws.put_page( query: "#{@api_url}#{api_query}",
+                                content_type: content_type,
+                                authorization: "token #{@auth_token}",
+                                data: body
+                              )
+        content_type = ws.header_value(key: 'Content-Type')
+      end
+      return iterate_json_response(response: response, content_type: content_type, debug: debug, &block)
+    end
+
+    # delete sends an HTML DELETE request.
+    # We don't expect to get a response to this call.
+    #
+    # @param api_query [String] base figshare api call
+    # @param debug [Boolean] print result to stdout
+    # @yield [Hash] Unlikely to have a result from delete calls, but if we do, we see it here
+    # @return [Integer] number of results (usually 0)
+    private def delete(api_query:, args: {}, debug: false, &block)
+      #ignoring args for the moment. Not sure what to do with them, if we do get them.
+      content_type = response = nil
+      WIKK::WebBrowser.https_session( host: @hostname, verify_cert: false ) do |ws|
+        response = ws.delete_req( query: "#{@api_url}#{api_query}",
+                                authorization: "token #{@auth_token}"
+                              )
+        content_type = ws.header_value(key: 'Content-Type')
+      end
+      return iterate_json_response(response: response, content_type: content_type, debug: debug, &block)
+    end
+    
+    # For iterate through the api response
+    #
+    # @param response [String] response from the API call
+    # @param content_type [String] From html response header
+    # @param debug [Boolean] print result to stdout
+    # @yield [Hash] each array member in the response (or the entire response, if not iteratable)
+    private def iterate_json_response(response:, content_type:, debug: false )
+      return 0 if response.nil? # got no responses
+      
+      if content_type =~ /application\/json/
+        response_array = JSON.parse(response)
+        #If we don't have an Array, turn the response into an Array so we can iterate over this one response.
+        response_array = [ response_array ] if ! (response_array.class == Array)
+        return 0 if response_array.empty? # got empty array of responses
+            
+        count = 0
+        response_array.each do |r|
+          yield r if block_given?
+          p r if debug
+          count += 1
+        end
+    
+        return count
+      else #just dump the entire response on the caller :)
+        yield response  if block_given?
+        return response.length
+      end
+    end
+  end
+end