Merge pull request #353 from MITLibraries/rest-api

Add protected ability to request JSON results with token

Author: matt-bernhardt

README.md

@@ -114,6 +114,7 @@ may have unexpected consequences if applied to other TIMDEX UI apps.
 - `FILTER_PLACE`: The name to use instead of "Place" for that filter / aggregation.
 - `FILTER_SOURCE`: The name to use instead of "Source" for that filter / aggregation.
 - `FILTER_SUBJECT`: The name to use instead of "Subject" for that filter / aggregation.
+- `FORMAT_TOKEN`: If defined, user agents can request results in JSON format by providing this value in the `format_token` querystring parameter.
 - `GLOBAL_ALERT`: The main functionality for this comes from our theme gem, but when set the value will be rendered as
   safe html above the main header of the site.
 - `THIRDIRON_KEY`: An access key assigned by Third Iron to enable this application to interact with the Libkey service.

app/controllers/search_controller.rb

@@ -1,5 +1,6 @@
 class SearchController < ApplicationController
   before_action :validate_q!, only: %i[results]
+  before_action :validate_format_token, only: %i[results]
   before_action :set_active_tab, only: %i[results]
   around_action :sleep_if_too_fast, only: %i[results]
 
@@ -33,6 +34,12 @@ def results
     when *timdex_tabs
       load_timdex_results
     end
+
+    # Render the response in HTML or JSON format
+    respond_to do |format|
+      format.json { render json: { results: @results, pagination: @pagination, errors: @errors } }
+      format.html { render :results }
+    end
   end
 
   private
@@ -381,4 +388,31 @@ def handle_primo_errors(error)
       [{ 'message' => error.message }]
     end
   end
+
+  # validate_format_token is only applicable to requests for JSON-format results. It takes no action so long as the
+  # valid_request_for_json? method returns true - otherwise it renders an error message with a 401 Unauthorized status.
+  def validate_format_token
+    return unless request.format.json?
+
+    return if valid_request_for_json?
+
+    render json: { error: 'Unauthorized request' }, status: :unauthorized
+  end
+
+  # valid_request_for_json? is responsible for validating whether a request for JSON format results is accompanied by
+  # a token which matches the value defined in env.
+  # 1. If the ENV is undefined, then the feature is not enabled - the check fails, which will prompt an Unauthorized
+  #    error.
+  # 2. If the ENV is defined, and the provided token matches, then the check fails, and the request will be honored.
+  # 3. In all other cases, the check fails, which will prompt the Unauthorized error.
+  def valid_request_for_json?
+    # Always fail unless the token is defined in ENV
+    return false unless ENV.fetch('FORMAT_TOKEN', '').present?
+
+    # Success if tokens match
+    return true if params[:format_token] == ENV.fetch('FORMAT_TOKEN', '')
+
+    # Otherwise fail
+    false
+  end
 end

test/controllers/search_controller_test.rb

@@ -1113,4 +1113,56 @@ def source_filter_count(controller)
     # Should show current range (21-40 for page 2)
     assert_select '.pagination-container .current', text: /21 - 40 of 800/
   end
+
+  test 'results can be returned in JSON format when env is set and valid token is provided' do
+    secret_value = 'sooper_sekret'
+    ClimateControl.modify FORMAT_TOKEN: secret_value do
+      mock_timdex_search_with_hits(10)
+      get "/results?q=test&format=json&format_token=#{secret_value}"
+      assert_response :success
+      assert_equal 'application/json; charset=utf-8', response.content_type
+    end
+  end
+
+  # We don't mock anything here because the error prevents any external lookups
+  test 'requests for JSON results without a token generate an unauthorized error' do
+    secret_value = 'sooper_sekret'
+    ClimateControl.modify FORMAT_TOKEN: secret_value do
+      get '/results?q=test&format=json'
+      assert_response :unauthorized
+    end
+  end
+
+  # We don't mock anything here because the error prevents any external lookups
+  test 'requests for JSON results when env var is not set generate an unauthorized error' do
+    secret_value = 'irrelevant'
+    ClimateControl.modify FORMAT_TOKEN: '' do
+      get "/results?q=test&format=json&format_token=#{secret_value}"
+      assert_response :unauthorized
+    end
+  end
+
+  # We don't mock anything here because the error prevents any external lookups
+  test 'requests for JSON results with an incorrect token generate an unauthorized error' do
+    secret_value = 'sooper_sekret'
+    wrong_secret = 'something_else'
+    refute_equal secret_value, wrong_secret
+
+    ClimateControl.modify FORMAT_TOKEN: secret_value do
+      get "/results?q=test&format=json&format_token=#{wrong_secret}"
+      assert_response :unauthorized
+    end
+  end
+
+  test 'requests with unsupported format receive a 406 not-acceptable error' do
+    mock_timdex_search_with_hits(10)
+    get '/results?q=test&format=xml'
+    assert_response :not_acceptable
+  end
+
+  test 'requests with invalid format receive a 406 not-acceptable error' do
+    mock_timdex_search_with_hits(10)
+    get '/results?q=test&format=foo'
+    assert_response :not_acceptable
+  end
 end