serrano 0.3.6 → 0.6.2

data/Rakefile

@@ -1,41 +1,49 @@
-require "bundler/gem_tasks"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
 require 'rake/testtask'
+require 'rubocop/rake_task'
 
 Rake::TestTask.new do |t|
-  t.libs << "test"
-  t.test_files = FileList['test/test-*.rb']
+  t.libs << 'test'
+  t.test_files = FileList['test/test_*.rb']
   t.verbose = true
+  t.warning = false
 end
 
-desc "Run tests"
-task :default => :test
+desc 'Run tests'
+task default: :test
+
+RuboCop::RakeTask.new(:rubocop) do |t|
+  t.options = ['--display-cop-names']
+end
 
-desc "Build serrano docs"
+desc 'Build serrano docs'
 task :docs do
-	system "yardoc"
+  system 'yardoc'
 end
 
-desc "bundle install"
+desc 'bundle install'
 task :bundle do
-  system "bundle install"
+  system 'bundle install'
 end
 
-desc "clean out builds"
+desc 'clean out builds'
 task :clean do
-  system "ls | grep [0-9].gem | xargs rm"
+  system 'ls | grep [0-9].gem | xargs rm'
 end
 
-desc "Build serrano"
+desc 'Build serrano'
 task :build do
-	system "gem build serrano.gemspec"
+  system 'gem build serrano.gemspec'
 end
 
-desc "Install serrano"
-task :install => [:bundle, :build] do
-	system "gem install serrano-#{Serrano::VERSION}.gem"
+desc 'Install serrano'
+task install: %i[bundle build] do
+  system "gem install serrano-#{Serrano::VERSION}.gem"
 end
 
-desc "Release to Rubygems"
-task :release => :build do
+desc 'Release to Rubygems'
+task release: :build do
   system "gem push serrano-#{Serrano::VERSION}.gem"
 end

data/bin/serrano

@@ -1,14 +1,15 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "thor"
-require "serrano"
-require "multi_json"
+require 'thor'
+require 'serrano'
+require 'multi_json'
 
 class Sr < Thor
   include Thor::Actions
   # class_option :json, :type => :boolean, :default => false
 
-  desc "works [DOIs]", "Get works by DOIs"
+  desc 'works [DOIs]', 'Get works by DOIs'
   long_desc <<-LONGDESC
     `serrano works` accepts one or more DOIs to search for works
 
@@ -47,17 +48,17 @@ class Sr < Thor
     \x5"http://orcid.org/0000-0003-4087-8021"
     \x5"http://orcid.org/0000-0002-2076-5452"
   LONGDESC
-  option :json, :type => :boolean, :default => false
-  option :filter, :type => :hash, :default => nil
-  option :limit, :type => :numeric, :default => nil
-  def works(ids=nil)
-    if ids.nil?
-      out = Serrano.works(filter: options[:filter], limit: options[:limit])
-    else
-      out = Serrano.works(ids: ids.split(","), filter: options[:filter])
-    end
+  option :json, type: :boolean, default: false
+  option :filter, type: :hash, default: nil
+  option :limit, type: :numeric, default: nil
+  def works(ids = nil)
+    out = if ids.nil?
+            Serrano.works(filter: options[:filter], limit: options[:limit])
+          else
+            Serrano.works(ids: ids.split(','), filter: options[:filter])
+          end
     if !options[:json]
-      out = out.collect { |x| x['message'].select { |k,v| k[/DOI|type|title/] } }
+      out = out.collect { |x| x['message'].select { |k, _v| k[/DOI|type|title/] } }
       out.each do |x|
         puts 'DOI: ' + x['DOI'].to_s
         puts 'type: ' + x['type']
@@ -69,7 +70,7 @@ class Sr < Thor
     end
   end
 
-  desc "members [member IDs]", "Get members by id"
+  desc 'members [member IDs]', 'Get members by id'
   long_desc <<-LONGDESC
     `serrano members` accepts one or more Crossref member IDs
 
@@ -96,26 +97,26 @@ class Sr < Thor
 
     24 7 45 31 22 67 72 17 53 75 0 68 12 16 50 79 40 18 40 195
   LONGDESC
-  option :json, :type => :boolean, :default => false
-  option :query, :type => :string, :default => nil
-  option :limit, :type => :numeric, :default => nil
-  option :works, :type => :boolean, :default => false
-  def members(ids=nil)
+  option :json, type: :boolean, default: false
+  option :query, type: :string, default: nil
+  option :limit, type: :numeric, default: nil
+  option :works, type: :boolean, default: false
+  def members(ids = nil)
     if ids.nil?
       out = Serrano.members(query: options[:query], limit: options[:limit],
-        works: options[:works])
+                            works: options[:works])
     else
-      out = Serrano.members(ids: ids.split(","), query: options[:query], limit: options[:limit],
-        works: options[:works])
+      out = Serrano.members(ids: ids.split(','), query: options[:query], limit: options[:limit],
+                            works: options[:works])
     end
 
     if !options[:json]
       if !options[:works]
-        if out.class == Hash
-          out = out['message']['items']
-        else
-          out = out.collect { |x| x['message'] }
-        end
+        out = if out.class == Hash
+                out['message']['items']
+              else
+                out.collect { |x| x['message'] }
+              end
 
         # out = out.collect { |x| x['message'].select { |k,v| k[/id|primary-name/] } }
         out.each do |x|
@@ -131,8 +132,7 @@ class Sr < Thor
     end
   end
 
-
-  desc "prefixes [DOI prefixes]", "Search for prefixes by DOI prefix"
+  desc 'prefixes [DOI prefixes]', 'Search for prefixes by DOI prefix'
   long_desc <<-LONGDESC
     `serrano prefixes` accepts one or more Crossref member IDs
 
@@ -162,24 +162,24 @@ class Sr < Thor
     \x5"Co-Action Publishing"
     \x5"Oxford University Press (OUP)"
   LONGDESC
-  option :json, :type => :boolean, :default => false
-  option :limit, :type => :numeric, :default => nil
-  option :works, :type => :boolean, :default => false
-  def prefixes(ids=nil)
-    if ids.nil?
-      out = Serrano.prefixes(limit: options[:limit], works: options[:works])
-    else
-      out = Serrano.prefixes(ids: ids.split(","), limit: options[:limit],
-        works: options[:works])
-    end
+  option :json, type: :boolean, default: false
+  option :limit, type: :numeric, default: nil
+  option :works, type: :boolean, default: false
+  def prefixes(ids = nil)
+    out = if ids.nil?
+            Serrano.prefixes(limit: options[:limit], works: options[:works])
+          else
+            Serrano.prefixes(ids: ids.split(','), limit: options[:limit],
+                             works: options[:works])
+          end
 
     if !options[:json]
       if !options[:works]
-        if out.class == Hash
-          out = out['message']['items']
-        else
-          out = out.collect { |x| x['message'] }
-        end
+        out = if out.class == Hash
+                out['message']['items']
+              else
+                out.collect { |x| x['message'] }
+              end
 
         out.each do |x|
           puts 'member: ' + x['member']
@@ -195,7 +195,7 @@ class Sr < Thor
     end
   end
 
-  desc "funders [funder IDs]", "Search for funders by DOI prefix"
+  desc 'funders [funder IDs]', 'Search for funders by DOI prefix'
   long_desc <<-LONGDESC
     `serrano funders` accepts one or more Crossref funder IDs
 
@@ -226,26 +226,26 @@ class Sr < Thor
 
     $ serrano funders 10.13039/100000001 --works=true --limit=2
   LONGDESC
-  option :json, :type => :boolean, :default => false
-  option :query, :type => :string, :default => nil
-  option :limit, :type => :numeric, :default => nil
-  option :works, :type => :boolean, :default => false
-  def funders(ids=nil)
+  option :json, type: :boolean, default: false
+  option :query, type: :string, default: nil
+  option :limit, type: :numeric, default: nil
+  option :works, type: :boolean, default: false
+  def funders(ids = nil)
     if ids.nil?
       out = Serrano.funders(query: options[:query], limit: options[:limit],
-        works: options[:works])
+                            works: options[:works])
     else
-      out = Serrano.funders(ids: ids.split(","), query: options[:query], limit: options[:limit],
-        works: options[:works])
+      out = Serrano.funders(ids: ids.split(','), query: options[:query], limit: options[:limit],
+                            works: options[:works])
     end
 
     if !options[:json]
       if !options[:works]
-        if out.class == Hash
-          out = out['message']['items']
-        else
-          out = out.collect { |x| x['message'] }
-        end
+        out = if out.class == Hash
+                out['message']['items']
+              else
+                out.collect { |x| x['message'] }
+              end
 
         out.each do |x|
           puts 'id: ' + x['id']
@@ -261,8 +261,7 @@ class Sr < Thor
     end
   end
 
-
-  desc "journals [journal ISSNs]", "Search for journals by ISSNs"
+  desc 'journals [journal ISSNs]', 'Search for journals by ISSNs'
   long_desc <<-LONGDESC
     `serrano journals` accepts one or more journal ISSNs
 
@@ -293,26 +292,26 @@ class Sr < Thor
 
     $ serrano journals 2167-8359 --query=ecology --works=true --limit=2
   LONGDESC
-  option :json, :type => :boolean, :default => false
-  option :query, :type => :string, :default => nil
-  option :limit, :type => :numeric, :default => nil
-  option :works, :type => :boolean, :default => false
-  def journals(ids=nil)
+  option :json, type: :boolean, default: false
+  option :query, type: :string, default: nil
+  option :limit, type: :numeric, default: nil
+  option :works, type: :boolean, default: false
+  def journals(ids = nil)
     if ids.nil?
       out = Serrano.journals(query: options[:query], limit: options[:limit],
-        works: options[:works])
+                             works: options[:works])
     else
-      out = Serrano.journals(ids: ids.split(","), query: options[:query], limit: options[:limit],
-        works: options[:works])
+      out = Serrano.journals(ids: ids.split(','), query: options[:query], limit: options[:limit],
+                             works: options[:works])
     end
 
     if !options[:json]
       if !options[:works]
-        if out.class == Hash
-          out = out['message']['items']
-        else
-          out = out.collect { |x| x['message'] }
-        end
+        out = if out.class == Hash
+                out['message']['items']
+              else
+                out.collect { |x| x['message'] }
+              end
 
         out.each do |x|
           puts 'ISSN: ' + x['ISSN'][0]
@@ -328,7 +327,7 @@ class Sr < Thor
     end
   end
 
-  desc "types [type name]", "Search for types by name"
+  desc 'types [type name]', 'Search for types by name'
   long_desc <<-LONGDESC
     `serrano types` accepts one or more type names
 
@@ -359,20 +358,20 @@ class Sr < Thor
 
     $ serrano types dissertation --works --limit=2
   LONGDESC
-  option :json, :type => :boolean, :default => false
-  option :works, :type => :boolean, :default => false
-  option :limit, :type => :numeric, :default => nil
+  option :json, type: :boolean, default: false
+  option :works, type: :boolean, default: false
+  option :limit, type: :numeric, default: nil
   def types(*ids)
     out = Serrano.types(ids: ids, limit: options[:limit],
-      works: options[:works])
+                        works: options[:works])
 
     if !options[:json]
       if !options[:works]
-        if out.class == Hash
-          out = out['message']['items']
-        else
-          out = out.collect { |x| x['message'] }
-        end
+        out = if out.class == Hash
+                out['message']['items']
+              else
+                out.collect { |x| x['message'] }
+              end
 
         out.each do |x|
           puts 'id: ' + x['id']
@@ -387,7 +386,7 @@ class Sr < Thor
     end
   end
 
-  desc "licenses", "Search for licenses by name"
+  desc 'licenses', 'Search for licenses by name'
   long_desc <<-LONGDESC
     `serrano licenses` accepts one or more type names
 
@@ -416,8 +415,8 @@ class Sr < Thor
     "National Science Foundation"
     \x5"U.S. Department of Energy"
   LONGDESC
-  option :json, :type => :boolean, :default => false
-  option :query, :type => :string, :default => nil
+  option :json, type: :boolean, default: false
+  option :query, type: :string, default: nil
   def licenses
     out = Serrano.licenses(query: options[:query])
     if !options[:json]
@@ -432,7 +431,7 @@ class Sr < Thor
     end
   end
 
-  desc "contneg", "Content negotiation"
+  desc 'contneg', 'Content negotiation'
   long_desc <<-LONGDESC
     `serrano contneg` accepts a DOI
 
@@ -444,15 +443,15 @@ class Sr < Thor
 
     Murtaugh PA (2014).  In defense of P values . Ecology 95: 611–617.
   LONGDESC
-  option :format, :type => :string, :default => "text"
-  option :style, :type => :string, :default => "apa"
-  option :locale, :type => :string, :default => "en-US"
+  option :format, type: :string, default: 'text'
+  option :style, type: :string, default: 'apa'
+  option :locale, type: :string, default: 'en-US'
   def contneg(ids)
     puts Serrano.content_negotiation(ids: ids, format: options[:format], style:
       options[:style], locale: options[:locale])
   end
 
-  desc "version", "Get serrano version"
+  desc 'version', 'Get serrano version'
   def version
     puts Serrano::VERSION
   end
@@ -460,11 +459,11 @@ class Sr < Thor
   private
 
   def print_works(data)
-    if data.is_a? Array
-      data = data[0]['message']['items']
-    else
-      data = data.collect { |x| x['message'].select { |k,v| k[/DOI|type|title/] } }
-    end
+    data = if data.is_a? Array
+             data[0]['message']['items']
+           else
+             data.collect { |x| x['message'].select { |k, _v| k[/DOI|type|title/] } }
+           end
     data.each do |x|
       puts 'DOI: ' + x['DOI']
       puts 'type: ' + x['type']
@@ -472,7 +471,6 @@ class Sr < Thor
       puts
     end
   end
-
 end
 
 Sr.start(ARGV)

data/lib/serrano.rb

@@ -1,10 +1,13 @@
-require "serrano/version"
-require "serrano/request"
-require "serrano/request_cursor"
-require "serrano/filterhandler"
-require "serrano/cnrequest"
-require "serrano/filters"
-require "serrano/styles"
+# frozen_string_literal: true
+
+require 'erb'
+require 'serrano/version'
+require 'serrano/request'
+require 'serrano/request_cursor'
+require 'serrano/filterhandler'
+require 'serrano/cnrequest'
+require 'serrano/filters'
+require 'serrano/styles'
 
 require 'rexml/document'
 require 'rexml/xpath'
@@ -18,13 +21,21 @@ require 'rexml/xpath'
 #       Max: 100.
 #   @param sort [String] Field to sort on, one of score, relevance,
 #       updated (date of most recent change to metadata - currently the same as deposited),
-#       deposited (time of most recent deposit), indexed (time of most recent index), or
-#       published (publication date). Note: If the API call includes a query, then the sort
+#       deposited (time of most recent deposit), indexed (time of most recent index),
+#       published (publication date), published-print (print publication date),
+#       published-online (online publication date), issued (issued date (earliest known publication date)),
+#       is-referenced-by-count (number of times this DOI is referenced by other Crossref DOIs), or
+#       references-count (number of references included in the references section of the document
+#       identified by this DOI). Note: If the API call includes a query, then the sort
 #       order will be by the relevance score. If no query is included, then the sort order
 #       will be by DOI update date.
 #   @param order [String] Sort order, one of 'asc' or 'desc'
 #   @param facet [Boolean/String] Include facet results OR a query (e.g., `license:*`) to facet by
 #       license. Default: false
+#   @param select [String/Array(String)] Crossref metadata records can be
+#       quite large. Sometimes you just want a few elements from the schema. You can "select"
+#       a subset of elements to return. This can make your API calls much more efficient. Not
+#       clear yet which fields are allowed here.
 #   @param verbose [Boolean] Print request headers to stdout. Default: false
 
 # @!macro cursor_params
@@ -52,10 +63,18 @@ require 'rexml/xpath'
 #     - oauth [Hash] A hash with OAuth details
 
 # @!macro field_queries
-#   @param [Hash<Object>] args Field queries, as named parameters.
-#       See https://github.com/CrossRef/rest-api-doc/blob/master/rest_api.md#field-queries
+#   @param [Hash<Object>] args Field queries, as named parameters. See
+#       https://github.com/CrossRef/rest-api-doc/blob/master/rest_api.md#field-queries
 #       Field query parameters mut be named, and must start with `query_`. Any dashes or
-#       periods should be replaced with underscores.
+#       periods should be replaced with underscores. The options include:
+#       - query_container_title: Query container-title aka. publication name
+#       - query_author: Query author given and family names
+#       - query_editor: Query editor given and family names
+#       - query_chair: Query chair given and family names
+#       - query_translator: Query translator given and family names
+#       - query_contributor: Query author, editor, chair and translator given and family names
+#       - query_bibliographic: Query bibliographic information, useful for citation look up. Includes titles, authors, ISSNs and publication years
+#       - query_affiliation: Query contributor affiliations
 
 ##
 # Serrano - The top level module for using methods
@@ -91,7 +110,29 @@ require 'rexml/xpath'
 # searching full text, or even abstracts of articles, but only what is
 # available in the data that is returned to you. That is, they search
 # article titles, authors, etc. For some discussion on this, see
-# https://github.com/CrossRef/rest-api-doc/issues/101
+# https://gitlab.com/crossref/issues/issues/101
+#
+#
+# The Polite Pool
+# As of September 18th 2017 any API queries that use HTTPS and have
+# appropriate contact information will be directed to a special pool
+# of API machines that are reserved for polite users. If you connect
+# to the Crossreef API using HTTPS and provide contact
+# information, then they will send you to a separate pool of machines,
+# with better control the performance of these machines because they can
+# block abusive users.
+#
+# We have been using `https` in `serrano` for a while now, so that's good
+# to go. To get into the Polite Pool, also set your `mailto` email address
+# with `Serrano.configuration` (example below), or set as an environment
+# variable with the name `CROSSREF_EMAIL` and your mailto will be set
+# for each request automatically.
+#
+# require 'serrano'
+# Serrano.configuration do |config|
+#   config.mailto = "foo@bar.com"
+# end
+#
 #
 # Rate limiting
 # Crossref introduced rate limiting recently. The rate limits apparently vary,
@@ -99,13 +140,20 @@ require 'rexml/xpath'
 # limit is 50 requests per second. Look for the headers `X-Rate-Limit-Limit`
 # and `X-Rate-Limit-Interval` in requests to see what the current rate
 # limits are.
+#
+#
+# URL Encoding
+# We do URL encoding of DOIs for you for all methods except `Serrano.citation_count`
+# which doesn't work if you encode DOIs beforehand. We use `ERB::Util.url_encode`
+# to encode.
 
 module Serrano
   extend Configuration
 
   define_setting :access_token
   define_setting :access_secret
-  define_setting :base_url, "https://api.crossref.org/"
+  define_setting :mailto, ENV['CROSSREF_EMAIL']
+  define_setting :base_url, 'https://api.crossref.org/'
 
   ##
   # Search the works route
@@ -154,8 +202,12 @@ module Serrano
   #      # sample
   #      Serrano.works(sample: 2)
   #
+  #      # select - pass an array or a comma separated string
+  #      Serrano.works(query: "ecology", select: "DOI,title", limit: 30)
+  #      Serrano.works(query: "ecology", select: ["DOI","title"], limit: 30)
+  #
   #      # cursor for deep paging
-  #      Serrano.works(query: "widget", cursor: "*", limit: 100)
+  #      Serrano.works(query: "widget", cursor: "*", limit: 100, cursor_max: 1000)
   #      # another query, more results this time
   #      res = Serrano.works(query: "science", cursor: "*", limit: 250, cursor_max: 1000);
   #      res.collect { |x| x['message']['items'].length }.reduce(0, :+)
@@ -173,13 +225,18 @@ module Serrano
   #      ## query.container-title
   #      res = Serrano.works(query: "ecology", query_container_title: 'Ecology')
   #      res['message']['items'].collect { |x| x['container-title'] }
+  #
+  #      # select certain fields
+  #      Serrano.works(select: ['DOI', 'title'], limit: 3)
   def self.works(ids: nil, query: nil, filter: nil, offset: nil,
-    limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
-    options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args)
+                 limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
+                 select: nil, options: nil, verbose: false, cursor: nil,
+                 cursor_max: 5000, **args)
 
+    assert_valid_filters(filter) if filter
     RequestCursor.new('works', ids, query, filter, offset,
-      limit, sample, sort, order, facet, nil, nil, options,
-      verbose, cursor, cursor_max, args).perform
+                      limit, sample, sort, order, facet, select, nil, nil, options,
+                      verbose, cursor, cursor_max, args).perform
   end
 
   ##
@@ -225,14 +282,18 @@ module Serrano
   #      ## query.title
   #      res = Serrano.members(ids: 221, works: true, query_container_title: 'Advances')
   #      res[0]['message']['items'].collect { |x| x['container-title'] }
+  #
+  #      # select certain fields
+  #      Serrano.members(ids: 340, works: true, select: ['DOI', 'title'], limit: 3)
   def self.members(ids: nil, query: nil, filter: nil, offset: nil,
-    limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
-    works: false, options: nil, verbose: false,
-    cursor: nil, cursor_max: 5000, **args)
+                   limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
+                   select: nil, works: false, options: nil, verbose: false,
+                   cursor: nil, cursor_max: 5000, **args)
 
+    assert_valid_filters(filter) if filter
     RequestCursor.new('members', ids, query, filter, offset,
-      limit, sample, sort, order, facet, works, nil, options,
-      verbose, cursor, cursor_max, args).perform
+                      limit, sample, sort, order, facet, select, works, nil,
+                      options, verbose, cursor, cursor_max, args).perform
   end
 
   ##
@@ -266,17 +327,21 @@ module Serrano
   #      items.collect{ |z| z['DOI'] }[0,50]
   #
   #      # field queries
-  #      ## query.title
-  #      res = Serrano.prefixes(ids: "10.1016", works: true, query_title: 'cell biology')
+  #      ## query.bibliographic
+  #      res = Serrano.prefixes(ids: "10.1016", works: true, query_bibliographic: 'cell biology')
   #      res[0]['message']['items'].collect { |x| x['title'] }
+  #
+  #      # select certain fields
+  #      Serrano.prefixes(ids: "10.1016", works: true, select: ['DOI', 'title'], limit: 3)
   def self.prefixes(ids:, filter: nil, offset: nil,
-    limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
-    works: false, options: nil, verbose: false,
-    cursor: nil, cursor_max: 5000, **args)
+                    limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
+                    select: nil, works: false, options: nil, verbose: false,
+                    cursor: nil, cursor_max: 5000, **args)
 
+    assert_valid_filters(filter) if filter
     RequestCursor.new('prefixes', ids, nil, filter, offset,
-      limit, sample, sort, order, facet, works, nil, options,
-      verbose, cursor, cursor_max, args).perform
+                      limit, sample, sort, order, facet, select, works, nil,
+                      options, verbose, cursor, cursor_max, args).perform
   end
 
   ##
@@ -318,14 +383,18 @@ module Serrano
   #      ## query.title
   #      res = Serrano.funders(ids: "10.13039/100000001", works: true, query_author: 'Simon')
   #      res[0]['message']['items'].collect { |x| x['author'][0]['family'] }
+  #
+  #      # select certain fields
+  #      Serrano.funders(ids: "10.13039/100000001", works: true, select: ['DOI', 'title'], limit: 3)
   def self.funders(ids: nil, query: nil, filter: nil, offset: nil,
-    limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
-    works: false, options: nil, verbose: false,
-    cursor: nil, cursor_max: 5000, **args)
+                   limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
+                   select: nil, works: false, options: nil, verbose: false,
+                   cursor: nil, cursor_max: 5000, **args)
 
+    assert_valid_filters(filter) if filter
     RequestCursor.new('funders', ids, query, filter, offset,
-      limit, sample, sort, order, facet, works, nil, options,
-      verbose, cursor, cursor_max, args).perform
+                      limit, sample, sort, order, facet, select, works, nil, options,
+                      verbose, cursor, cursor_max, args).perform
   end
 
   ##
@@ -367,14 +436,18 @@ module Serrano
   #      ## query.title
   #      res = Serrano.journals(ids: "2167-8359", works: true, query_container_title: 'Advances')
   #      res[0]['message']['items'].collect { |x| x['container-title'] }
+  #
+  #      # select certain fields
+  #      Serrano.journals(ids: "2167-8359", works: true, select: ['DOI', 'title'], limit: 3)
   def self.journals(ids: nil, query: nil, filter: nil, offset: nil,
-    limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
-    works: false, options: nil, verbose: false,
-    cursor: nil, cursor_max: 5000, **args)
+                    limit: nil, sample: nil, sort: nil, order: nil, facet: nil,
+                    select: nil, works: false, options: nil, verbose: false,
+                    cursor: nil, cursor_max: 5000, **args)
 
+    assert_valid_filters(filter) if filter
     RequestCursor.new('journals', ids, query, filter, offset,
-      limit, sample, sort, order, facet, works, nil, options,
-      verbose, cursor, cursor_max, args).perform
+                      limit, sample, sort, order, facet, select, works, nil, options,
+                      verbose, cursor, cursor_max, args).perform
   end
 
   ##
@@ -385,6 +458,10 @@ module Serrano
   # @!macro field_queries
   # @param ids [Array] DOIs (digital object identifier) or other identifiers
   # @param works [Boolean] If true, works returned as well. Default: false
+  # @param select [String/Array(String)] Crossref metadata records can be
+  #     quite large. Sometimes you just want a few elements from the schema. You can "select"
+  #     a subset of elements to return. This can make your API calls much more efficient. Not
+  #     clear yet which fields are allowed here.
   # @return [Array] An array of hashes
   #
   # @example
@@ -404,20 +481,42 @@ module Serrano
   #      ## query.title
   #      res = Serrano.types(ids: "journal", works: true, query_container_title: 'Advances')
   #      res[0]['message']['items'].collect { |x| x['container-title'] }
-  def self.types(ids: nil, offset: nil, limit: nil, works: false,
-    options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args)
+  #
+  #      # select certain fields
+  #      Serrano.types(ids: "journal", works: true, select: ['DOI', 'title'], limit: 3)
+  def self.types(ids: nil, offset: nil, limit: nil, select: nil, works: false,
+                 options: nil, verbose: false, cursor: nil, cursor_max: 5000, **args)
 
     RequestCursor.new('types', ids, nil, nil, offset,
-      limit, nil, nil, nil, nil, works, nil, options,
-      verbose, cursor, cursor_max, args).perform
+                      limit, nil, nil, nil, nil, select, works, nil, options,
+                      verbose, cursor, cursor_max, args).perform
   end
 
   ##
   # Search the licenses route
   #
-  # @!macro serrano_params
   # @!macro serrano_options
   # @param query [String] A query string
+  # @param offset [Fixnum] Number of record to start at, any non-negative integer up to 10,000
+  # @param limit [Fixnum] Number of results to return. Not relavant when searching with specific dois.
+  #       Default: 20. Max: 1000
+  # @param sample [Fixnum] Number of random results to return. when you use the sample parameter,
+  #       the limit and offset parameters are ignored. This parameter only used when works requested.
+  #       Max: 100.
+  # @param sort [String] Field to sort on, one of score, relevance,
+  #       updated (date of most recent change to metadata - currently the same as deposited),
+  #       deposited (time of most recent deposit), indexed (time of most recent index),
+  #       published (publication date), published-print (print publication date),
+  #       published-online (online publication date), issued (issued date (earliest known publication date)),
+  #       is-referenced-by-count (number of times this DOI is referenced by other Crossref DOIs), or
+  #       references-count (number of references included in the references section of the document
+  #       identified by this DOI). Note: If the API call includes a query, then the sort
+  #       order will be by the relevance score. If no query is included, then the sort order
+  #       will be by DOI update date.
+  # @param order [String] Sort order, one of 'asc' or 'desc'
+  # @param facet [Boolean/String] Include facet results OR a query (e.g., `license:*`) to facet by
+  #       license. Default: false
+  # @param verbose [Boolean] Print request headers to stdout. Default: false
   # @return [Array] An array of hashes
   #
   # @example
@@ -426,11 +525,11 @@ module Serrano
   #      Serrano.licenses()
   #      Serrano.licenses(limit: 3)
   def self.licenses(query: nil, offset: nil,
-    limit: nil, sample: nil, sort: nil, order: nil,
-    facet: nil, options: nil, verbose: false)
+                    limit: nil, sample: nil, sort: nil, order: nil,
+                    facet: nil, options: nil, verbose: false)
 
     Request.new('licenses', nil, query, nil, offset,
-      limit, sample, sort, order, facet, nil, nil, options, verbose).perform
+                limit, sample, sort, order, facet, nil, nil, nil, options, verbose).perform
   end
 
   ##
@@ -445,9 +544,8 @@ module Serrano
   #      Serrano.registration_agency(ids: '10.1371/journal.pone.0033693')
   #      Serrano.registration_agency(ids: ['10.1007/12080.1874-1746','10.1007/10452.1573-5125', '10.1111/(issn)1442-9993'])
   def self.registration_agency(ids:, options: nil, verbose: false)
-
     Request.new('works', ids, nil, nil, nil,
-      nil, nil, nil, nil, nil, false, true, options, verbose).perform
+                nil, nil, nil, nil, nil, nil, false, true, options, verbose).perform
   end
 
   ##
@@ -468,9 +566,8 @@ module Serrano
   #      Serrano.random_dois(sample: 10)
   #      Serrano.random_dois(sample: 100)
   def self.random_dois(sample: 10, options: nil, verbose: false)
-
     tmp = Request.new('works', nil, nil, nil, nil,
-      nil, sample, nil, nil, nil, false, nil, options, verbose).perform
+                      nil, sample, nil, nil, nil, nil, false, nil, options, verbose).perform
     tmp['message']['items'].collect { |x| x['DOI'] }
   end
 
@@ -497,7 +594,7 @@ module Serrano
   #     Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "crossref-xml")
   #     Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "text")
   #
-  #     # return an R bibentry type
+  #     # return a bibentry type
   #     Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "bibentry")
   #     Serrano.content_negotiation(ids: "10.6084/m9.figshare.97218", format: "bibentry")
   #
@@ -510,30 +607,32 @@ module Serrano
   #     Serrano.content_negotiation(ids: "10.1126/science.169.3946.635", format: "text", style: "oikos")
   #
   #     # example with many DOIs
-  #     dois = cr_r(2)
-  #     Serrano.content_negotiation(dois, format: "text", style: "apa")
+  #     dois = Serrano.random_dois(sample: 2)
+  #     Serrano.content_negotiation(ids: dois, format: "text", style: "apa")
   #
   #     # Using DataCite DOIs
-  #     ## some formats don't work
-  #     # Serrano.content_negotiation(ids: "10.5284/1011335", format: "text")
-  #     # Serrano.content_negotiation(ids: "10.5284/1011335", format: "crossref-xml")
-  #     # Serrano.content_negotiation(ids: "10.5284/1011335", format: "crossref-tdm")
+  #     doi = "10.1126/science.169.3946.635"
+  #     Serrano.content_negotiation(ids: doi, format: "text")
+  #     Serrano.content_negotiation(ids: doi, format: "crossref-xml")
+  #     Serrano.content_negotiation(ids: doi, format: "crossref-tdm")
   #
   #     ## But most do work
-  #     Serrano.content_negotiation(ids: "10.5284/1011335", format: "datacite-xml")
-  #     Serrano.content_negotiation(ids: "10.5284/1011335", format: "rdf-xml")
-  #     Serrano.content_negotiation(ids: "10.5284/1011335", format: "turtle")
-  #     Serrano.content_negotiation(ids: "10.5284/1011335", format: "citeproc-json")
-  #     Serrano.content_negotiation(ids: "10.5284/1011335", format: "ris")
-  #     Serrano.content_negotiation(ids: "10.5284/1011335", format: "bibtex")
-  #     Serrano.content_negotiation(ids: "10.5284/1011335", format: "bibentry")
-  #     Serrano.content_negotiation(ids: "10.5284/1011335", format: "bibtex")
+  #     Serrano.content_negotiation(ids: doi, format: "datacite-xml")
+  #     Serrano.content_negotiation(ids: doi, format: "rdf-xml")
+  #     Serrano.content_negotiation(ids: doi, format: "turtle")
+  #     Serrano.content_negotiation(ids: doi, format: "citeproc-json")
+  #     Serrano.content_negotiation(ids: doi, format: "ris")
+  #     Serrano.content_negotiation(ids: doi, format: "bibtex")
+  #     Serrano.content_negotiation(ids: doi, format: "bibentry")
+  #     Serrano.content_negotiation(ids: doi, format: "bibtex")
   #
   #     # many DOIs
-  #     dois = ['10.5167/UZH-30455','10.5167/UZH-49216','10.5167/UZH-503', '10.5167/UZH-38402','10.5167/UZH-41217']
+  #     dois = ['10.5167/UZH-30455','10.5167/UZH-49216','10.5167/UZH-503',
+  #      '10.5167/UZH-38402','10.5167/UZH-41217']
   #     x = Serrano.content_negotiation(ids: dois)
   #     puts x
-  def self.content_negotiation(ids:, format: "bibtex", style: 'apa', locale: "en-US")
+  def self.content_negotiation(ids:, format: 'bibtex', style: 'apa', locale: 'en-US')
+    ids = Array(ids).map { |x| ERB::Util.url_encode(x) }
     CNRequest.new(ids, format, style, locale).perform
   end
 
@@ -552,17 +651,17 @@ module Serrano
   #   Serrano.citation_count(doi: "10.1016/j.fbr.2012.01.001")
   #   # DOI not found
   #   Serrano.citation_count(doi: "10.1016/j.fbr.2012")
-  def self.citation_count(doi:, url: "http://www.crossref.org/openurl/",
-    key: "cboettig@ropensci.org", options: nil)
+  def self.citation_count(doi:, url: 'https://www.crossref.org/openurl/',
+                          key: 'cboettig@ropensci.org', options: nil)
 
-    args = { id: "doi:" + doi, pid: key, noredirect: true }
-    opts = args.delete_if { |k, v| v.nil? }
-    conn = Faraday.new(:url => url, :request => options)
+    args = { id: 'doi:' + doi, pid: key, noredirect: true }
+    opts = args.delete_if { |_k, v| v.nil? }
+    conn = Faraday.new(url: url, request: options)
     res = conn.get '', opts
     x = res.body
     oc = REXML::Document.new("<doc>#{x}</doc>")
     value = REXML::XPath.first(oc, '//query').attributes['fl_count'].to_i
-    return value
+    value
   end
 
   # Get csl styles
@@ -572,7 +671,25 @@ module Serrano
   # @example
   #   Serrano.csl_styles
   def self.csl_styles
-    get_styles()
+    fetch_styles
   end
 
+  def self.assert_valid_filters(filters)
+    unless filters.is_a? Hash
+      raise ArgumentError, <<~ERR
+        Filters must be provided as a hash, like:
+
+            Serrano.works(query: "something", filters: { has_abstract: true })
+      ERR
+    end
+
+    filters.each do |name, _|
+      filter_strings = Filters.names.map(&:to_s)
+      next if filter_strings.include?(name.to_s)
+
+      raise ArgumentError, <<~ERR
+        The filter "#{name}" is not a valid filter. Please run `Serrano.filters.filters` to see all valid filters.
+      ERR
+    end
+  end
 end