blazer_json_api 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bb70c37952526ddd6429985da872163b1220406a97af427aa0787db0e9fb371
-  data.tar.gz: bb3e7718fec2af8cfaf95d25a383b138f4db11d35c888a0e7907f89bd59cf87d
+  metadata.gz: 59f80fa45e2a211955055a9833d63c75115e7a7b7ddc80dff0953551cb98994c
+  data.tar.gz: 004add471a763d719345a3c2de853d0ccbdadd432ffaddcaed8d63c51de7a08a
 SHA512:
-  metadata.gz: 37f319479257cf68de348e8d0bcabe5fcef9d3a7dd7d611665346255089d5cb44eee40288432b3f3a8d18e9bcff03d5769740de22b24ee71f6dfbab5b4cbccc1
-  data.tar.gz: d4ce2dddc2eb910547761689705c431a5541b7031b87d154c4c758a04046cb8a721559ab61bc2e5f2230ae0ec79a4ecd6d90c0f961f284984de7c63f847b32aa
+  metadata.gz: c3936cafc9e5edebc527d3dff0618e42f8544e816c6cc6b8dce611169a7cec1a77eb5984582d4a701164dc0562013f003ccbc74ae12904e0f0d53a1cfae85b04
+  data.tar.gz: 9673d8c148f944fbb24fa3914b655961153eaf95a0a2fc91ce30de532fd465f089fc0b2ace2690cbf2b49c70e4d8a88cbd61f865927c50a7d0084e7cff015268

data/README.md

@@ -1,17 +1,20 @@
 # Blazer JSON API
-An extension to [Blazer](https://github.com/ankane/blazer) to enable exposing your queries as JSON via API so it can be consumed outside of Blazer by your application.
+An extension to [Blazer](https://github.com/ankane/blazer) to enable exposing your queries as JSON via API, so that they can be consumed outside of Blazer by your application.
+Use Blazer for powering in app charts using a charting library of your choice.
 
 ## Features
-- **Powered by SQL** Author APIs quickly using Blazers IDE. Particular useful for private/internal APIs that fall outside of your standard API endpoints
-- **No deploy APIs** Expermental APIs can be authored quickly via Blazer without the need to do a deploy
-- **Flexible structure** JSON response structure can be controlled directly in SQL by using a column naming convention (double underscore denotes a nesting by default, but can be overridden)
-- **Security** You'll likely want to lock down API access so APIs are authenticated separately to standard Blazer authentication using HTTP basic authentication to avoid granding everyone with access to Blazer also access to your APIs. 
-- **URL parameters** URL parameters are also supported built on Blazers query variables meaning the APIs can be highly dynamic and flexible
+- **Powered by SQL** Author APIs quickly using Blazers SQL based IDE. Particular useful for private/internal APIs that fall outside your standard API endpoints or where responses need to be taylored to suit a specific charting library.
+- **No deploy APIs** Experimental APIs can be authored and iterated on quickly via Blazer without the need to do a deploy. Were a team is split between frontend and backend, this greatly increases collaboration and speed.
+- **Flexible structure** JSON response structure can be controlled directly in SQL by using a column naming convention (double underscore `__` denotes a nesting by default, but can be overridden)
+- **Security** You'll likely want to lock down API access so APIs are authenticated separately to the standard Blazer auth model, so authentication is enabled using HTTP basic authentication to avoid granting everyone with access to Blazer also access to your APIs.
+- **URL parameters** URL parameters are also supported via Blazers query variables meaning the APIs can be highly dynamic and flexible
 - **Pagination** Pagination can be controlled using query variables in combination with limits and offsets
-- **Multiple data sources** Blazer supports multiple datasources meaning you can potentially build APIs that access beyond the applications database (e.g. ElasticSearch, Google BigQuery, Salesforce)
+- **Multiple data sources** Blazer supports multiple data sources meaning you can potentially build APIs that access beyond the applications' database (e.g. ElasticSearch, Google BigQuery, SalesForce etc)
+- **Permissions** Use Blazers [basic permissions mode](https://github.com/ankane/blazer#query-permissions) with your own naming conventions to control access and visibility of API based queries.
 
 ## Installation
-Follow the installation steps described to get Blazer up and running.
+Follow the installation steps described to get [Blazer](https://github.com/ankane/blazer#installation) up and running.
+
 Then, add this line to your application's Gemfile:
 
 ```ruby
@@ -26,30 +29,172 @@ $ bundle
 And mount the engine in your `config/routes.rb`:
 
 ```ruby
-mount BlazerJsonAPI, at: 'blazer-api'
+mount BlazerJsonAPI::Engine, at: 'blazer-api'
 ```
 
 Configure authentication in an initializer as follows (e.g. in `initializers/blazer_json_api.rb`)
 
 ```ruby
-BlazerJsonAPI::Config.username = <api-username>
-BlazerJsonAPI::Config.password = <api-password>
+BlazerJsonAPI.configure do |config|
+  config.username = 'api-username'
+  config.password = 'api-password'
+end
 ```
 
 ## Usage
-Create queries as normal via Blazer and use the query identifier to render the JSON via the mounted location. 
+Create queries as normal via Blazer and use the query identifier to render the JSON via the mounted location.
+
+e.g. `/blazer-api/queries/1-all-users` or `/blazer-api/queries/1`
+
+URL params can be added where necessary also
 
-e.g. `/blazer-api/queries/1-all-users`
+e.g. `/blazer-api/queries/1-all-users?username=blazer_user`
 
 ### Example queries
 
+#### A simple index like request
+Fetching specifics of all users as follows:
 
-> TODO
+```sql
+SELECT id, username, first_name, last_name, email, country
+FROM users
+```
+This would result in the following API response
+```json
+[
+  {
+    "id":1,
+    "username":"blazer_tommy",
+    "first_name":"Tom",
+    "last_name":"Carey",
+    "email":"tom.carey@gmail.com",
+    "country":"Ireland"
+  },
+  {
+    "id":2,
+    "username":"blazer_john",
+    "first_name":"John",
+    "last_name":"Doyle",
+    "email":"john.doyle@gmail.com",
+    "country":"USA"
+  }
+]
+```
+#### A simple single resource GET request using a variable
 
-## Contributing
+Using a variable, a specific resource can be fetched.
+
+**Note:** the use of `LIMIT 1` can be used to be explicit in desiring a single record in the response, as opposed to a collection
+
+```sql
+SELECT id, username, first_name, last_name, email, country
+FROM users
+WHERE username={username}
+LIMIT 1
+```
+Now, the username can be passed as a URL parameter to the API to fetch the relevant record.
+
+e.g. `/blazer-api/queries/1-all-users?username=blazer_john`
+
+It would result in the following response.
+
+```json
+{
+  "id":2,
+  "username":"blazer_john",
+  "first_name":"John",
+  "last_name":"Doyle",
+  "email":"john.doyle@gmail.com",
+  "country":"USA"
+}
+```
+#### Controlling response structure
+Standard queries return flat JSON responses that correspond to the results table from executing the SQL.
+
+It's possible to control the JSON structure by using double underscores to denote the desired nesting
+
+Take, for example, the following query:
+
+```sql
+SELECT users.id, username, first_name, last_name, teams.name as team__name, teams.location as team__location, email
+FROM users
+JOIN users ON users.team_id = teams.id
+```
 
+Would result in the following structure in the response:
+
+```json
+[
+  {
+    "id":1,
+    "username":"blazer_tommy",
+    "first_name":"Tom",
+    "last_name":"Carey",
+    "team":{
+      "name":"defenders",
+      "location":"Dublin"
+    },
+    "email":"tom.carey@gmail.com"
+  },
+  {
+    "id":2,
+    "username":"blazer_john",
+    "first_name":"John",
+    "last_name":"Doyle",
+    "team":{
+      "name":"responders",
+      "location":"London"
+    },
+    "email":"john.doyle@gmail.com"
+  }
+]
+```
+Deeper nesting is also possible, just continue the pattern e.g. `a__deeper__nested__value`
+
+#### Paginating potentially large responses
+If your query could return a large response, it's generally a good idea to paginate it.
+
+Pagination can be achieved in many ways, but a basic example can be done as follows using a combination
+of variables in the query and `LIMIT` and `OFFSET`.
+
+```sql
+SELECT id, username, first_name, last_name, email, country
+FROM users
+LIMIT {per_page}
+OFFSET ({page}-1)*{per_page}
+```
+Using this technique, URL params can be used by the requester to control pagination.
+
+In this example, `page` corresponds to the desired page in the paginated collection and `per_page` corresponds to the desired size of records in each page
+
+This technique can be used in combination with some default settings for these parameters in blazers config file `blazer.yml`.
+
+Having defaults means if they are not specified by the requester, the defaults will automatically be applied.
+```yaml
+    variable_defaults:
+      # pagination defaults
+      per_page: 30
+      page: 1
+```
+
+Requests can then be as follows:
+
+`/blazer-api/queries/1-all-users` = returns first 30 users (pagination defaults apply automatically)
+
+`/blazer-api/queries/1-all-users?page=2` = returns second page containing 30 users
+
+`/blazer-api/queries/1-all-users?page=1&per_page=90` = returns first page containing 90 users
+
+
+etc...
+
+## Contributing
+Want to improve this library, please do!
 
-> TODO
+* Report bugs
+* Fix bugs and submit pull requests
+* Write, clarify, or fix documentation
+* Suggest or add new features
 
 ## License
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/app/controllers/blazer_json_api/application_controller.rb

@@ -1,15 +1,27 @@
 # frozen_string_literal: true
 
-module BlazerJsonAPI
+module BlazerJsonApi
   class ApplicationController < ActionController::Base
+
+    if BlazerJsonAPI.credentials_provided?
+      http_basic_authenticate_with name: BlazerJsonAPI.username, password: BlazerJsonAPI.password
+    end
+
     protect_from_forgery with: :exception
+    before_action :check_authentication
 
     def record_not_found
       render json: [], status: :not_found
     end
 
-    def render_errors(error_messages)
-      render json: { errors: error_messages }, status: :bad_request
+    def render_errors(error_messages, status: :bad_request)
+      render json: { errors: error_messages }, status: status
+    end
+
+    def check_authentication
+      return if BlazerJsonAPI.credentials_provided?
+
+      render_errors(['Authentication credentials not set'], status: :unauthorized)
     end
   end
 end

data/app/controllers/blazer_json_api/queries_controller.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
-module BlazerJsonAPI
+module BlazerJsonApi
   class QueriesController < ApplicationController
-    if BlazerJsonAPI::Config.username && BlazerJsonAPI::Config.password
-      http_basic_authenticate_with name: BlazerJsonAPI::Config.username, password: BlazerJsonAPI::Config.password
-    end
     before_action :set_query
 
     def show

data/app/helpers/blazer_json_api/application_helper.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module BlazerJsonAPI
+module BlazerJsonApi
   module ApplicationHelper
   end
 end

data/app/jobs/blazer_json_api/application_job.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module BlazerJsonAPI
+module BlazerJsonApi
   class ApplicationJob < ActiveJob::Base
   end
 end

data/app/mailers/blazer_json_api/application_mailer.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module BlazerJsonAPI
+module BlazerJsonApi
   class ApplicationMailer < ActionMailer::Base
     default from: 'from@example.com'
     layout 'mailer'

data/app/models/blazer_json_api/application_record.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module BlazerJsonAPI
+module BlazerJsonApi
   class ApplicationRecord < ActiveRecord::Base
     self.abstract_class = true
   end

data/lib/blazer_json_api/configuration.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module BlazerJsonAPI
+  module Configuration
+
+    VALID_OPTIONS_KEYS = %i[username password nesting_column_separator].freeze
+
+    DEFAULT_USERNAME = nil
+    DEFAULT_PASSWORD = nil
+    DEFAULT_NESTING_COLUMN_SEPARATOR = '__'.freeze
+
+    attr_accessor(*VALID_OPTIONS_KEYS)
+
+    def self.extended(base)
+      base.reset_config!
+    end
+
+    # Convenience method to allow configuration options to be set in a block
+    # e.g. in an initializer for the application
+    def configure
+      yield self
+    end
+
+    def credentials_provided?
+      username.present? && password.present?
+    end
+
+    def reset_config!
+      self.username     = DEFAULT_USERNAME
+      self.password     = DEFAULT_PASSWORD
+      self.nesting_column_separator  = DEFAULT_NESTING_COLUMN_SEPARATOR
+    end
+  end
+end

data/lib/blazer_json_api/engine.rb

@@ -3,5 +3,9 @@
 module BlazerJsonAPI
   class Engine < ::Rails::Engine
     isolate_namespace BlazerJsonAPI
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
   end
 end

data/lib/blazer_json_api/result_to_nested_json.rb

@@ -5,7 +5,7 @@
 # e.g. { 'parent__child': '1' } becomes { 'parent': { 'child': 1 }}
 module BlazerJsonAPI
   class ResultToNestedJson
-    delegate :nesting_column_separator, to: BlazerJsonAPI::Config
+    delegate :nesting_column_separator, to: BlazerJsonAPI
 
     attr_reader :statement, :blazer_result
 

data/lib/blazer_json_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BlazerJsonAPI
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 end

data/lib/blazer_json_api.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 require 'blazer_json_api/engine'
-require 'blazer_json_api/config'
+require 'blazer_json_api/configuration'
 require 'blazer_json_api/process_statement_variables'
 require 'blazer_json_api/result_to_nested_json'
 
 module BlazerJsonAPI
+  extend BlazerJsonAPI::Configuration
 end

data/spec/rails_helper.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# This file is copied to spec/ when you run 'rails generate rspec:install'
+require 'spec_helper'
+ENV['RAILS_ENV'] ||= 'test'
+require File.expand_path('../config/environment', __dir__)
+# Prevent database truncation if the environment is production
+if Rails.env.production?
+  abort('The Rails environment is running in production mode!')
+end
+require 'rspec/rails'
+# Add additional requires below this line. Rails is not loaded until this point!
+
+# Requires supporting ruby files with custom matchers and macros, etc, in
+# spec/support/ and its subdirectories. Files matching `spec/**/*_spec.rb` are
+# run as spec files by default. This means that files in spec/support that end
+# in _spec.rb will both be required and run as specs, causing the specs to be
+# run twice. It is recommended that you do not name files matching this glob to
+# end with _spec.rb. You can configure this pattern with the --pattern
+# option on the command line or in ~/.rspec, .rspec or `.rspec-local`.
+#
+# The following line is provided for convenience purposes. It has the downside
+# of increasing the boot-up time by auto-requiring all files in the support
+# directory. Alternatively, in the individual `*_spec.rb` files, manually
+# require only the support files necessary.
+#
+# Dir[Rails.root.join('spec', 'support', '**', '*.rb')].sort.each do |f|
+#   require f
+# end
+
+# Checks for pending migrations and applies them before tests are run.
+# If you are not using ActiveRecord, you can remove these lines.
+begin
+  ActiveRecord::Migration.maintain_test_schema!
+rescue ActiveRecord::PendingMigrationError => e
+  puts e.to_s.strip
+  exit 1
+end
+RSpec.configure do |config|
+  # Remove this line if you're not using ActiveRecord or ActiveRecord fixtures
+  config.fixture_path = "#{::Rails.root}/spec/fixtures"
+
+  # If you're not using ActiveRecord, or you'd prefer not to run each of your
+  # examples within a transaction, remove the following line or assign false
+  # instead of true.
+  config.use_transactional_fixtures = true
+
+  # You can uncomment this line to turn off ActiveRecord support entirely.
+  # config.use_active_record = false
+
+  # RSpec Rails can automatically mix in different behaviours to your tests
+  # based on their file location, for example enabling you to call `get` and
+  # `post` in specs under `spec/controllers`.
+  #
+  # You can disable this behaviour by removing the line below, and instead
+  # explicitly tag your specs with their type, e.g.:
+  #
+  #     RSpec.describe UsersController, type: :controller do
+  #       # ...
+  #     end
+  #
+  # The different available types are documented in the features, such as in
+  # https://relishapp.com/rspec/rspec-rails/docs
+  config.infer_spec_type_from_file_location!
+
+  # Filter lines from Rails gems in backtraces.
+  config.filter_rails_from_backtrace!
+  # arbitrary gems may also be filtered via:
+  # config.filter_gems_from_backtrace("gem name")
+end

data/spec/spec_helper.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+# This file was generated by the `rails generate rspec:install` command.
+# Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# The generated `.rspec` file contains `--require spec_helper` which will cause
+# this file to always be loaded, without a need to explicitly require it in any
+# files.
+#
+# Given that it is always loaded, you are encouraged to keep this file as
+# light-weight as possible. Requiring heavyweight dependencies from this file
+# will add to the boot time of your test suite on EVERY test run, even for an
+# individual file that may not need all of that loaded. Instead, consider making
+# a separate helper file that requires the additional dependencies and performs
+# the additional setup, and require it from the spec files that actually need
+# it.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    #     be_bigger_than(2).and_smaller_than(4).description
+    #     # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #     # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+  # This option will default to `:apply_to_host_groups` in RSpec 4 (and will
+  # have no way to turn it off -- the option exists only for backwards
+  # compatibility in RSpec 3). It causes shared context metadata to be
+  # inherited by the metadata hash of host groups and examples, rather than
+  # triggering implicit auto-inclusion in groups with matching metadata.
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+
+  # The settings below are suggested to provide a good initial experience
+  # with RSpec, but feel free to customize to your heart's content.
+  #   # This allows you to limit a spec run to individual examples or groups
+  #   # you care about by tagging them with `:focus` metadata. When nothing
+  #   # is tagged with `:focus`, all examples get run. RSpec also provides
+  #   # aliases for `it`, `describe`, and `context` that include `:focus`
+  #   # metadata: `fit`, `fdescribe` and `fcontext`, respectively.
+  #   config.filter_run_when_matching :focus
+  #
+  #   # Allows RSpec to persist some state between runs in order to support
+  #   # the `--only-failures` and `--next-failure` CLI options. We recommend
+  #   # you configure your source control system to ignore this file.
+  #   config.example_status_persistence_file_path = "spec/examples.txt"
+  #
+  #   # Limits the available syntax to the non-monkey patched syntax that is
+  #   # recommended. For more details, see:
+  #   #   - http://rspec.info/blog/2012/06/rspecs-new-expectation-syntax/
+  #   #   - http://www.teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/
+  #   #   - http://rspec.info/blog/2014/05/notable-changes-in-rspec-3/#zero-monkey-patching-mode
+  #   config.disable_monkey_patching!
+  #
+  #   # Many RSpec users commonly either run the entire suite or an individual
+  #   # file, and it's useful to allow more verbose output when running an
+  #   # individual spec file.
+  #   if config.files_to_run.one?
+  #     # Use the documentation formatter for detailed output,
+  #     # unless a formatter has already been configured
+  #     # (e.g. via a command-line flag).
+  #     config.default_formatter = "doc"
+  #   end
+  #
+  #   # Print the 10 slowest examples and example groups at the
+  #   # end of the spec run, to help surface which specs are running
+  #   # particularly slow.
+  #   config.profile_examples = 10
+  #
+  #   # Run specs in random order to surface order dependencies. If you find an
+  #   # order dependency and want to debug it, you can fix the order by
+  #   # providing
+  #   # the seed, which is printed after each run.
+  #   #     --seed 1234
+  #   config.order = :random
+  #
+  #   # Seed global randomization in this process using the `--seed` CLI option.
+  #   # Setting this allows you to use `--seed` to deterministically
+  #   # reproduce
+  #   # test failures related to randomization by passing the same `--seed`
+  #   # value
+  #   # as the one that triggered the failure.
+  #   Kernel.srand config.seed
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: blazer_json_api
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - John Farrell
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-11-02 00:00:00.000000000 Z
+date: 2021-11-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -55,7 +55,7 @@ dependencies:
 description: An extension to the Blazer gem that makes it possible to expose queries
   as APIs
 email:
-- john.m.farrell1@gmail.com
+- john.farrell@andopen.co
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -75,17 +75,19 @@ files:
 - app/views/layouts/blazer_json_api/application.html.erb
 - config/routes.rb
 - lib/blazer_json_api.rb
-- lib/blazer_json_api/config.rb
+- lib/blazer_json_api/configuration.rb
 - lib/blazer_json_api/engine.rb
 - lib/blazer_json_api/process_statement_variables.rb
 - lib/blazer_json_api/result_to_nested_json.rb
 - lib/blazer_json_api/version.rb
 - lib/tasks/blazer_json_api_tasks.rake
-homepage: https://github.com/johnmfarrell1/blazer_json_api
+- spec/rails_helper.rb
+- spec/spec_helper.rb
+homepage: https://gitlab.com/andopen/blazer_json_api
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -93,15 +95,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.4'
+      version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.1.2
+signing_key:
 specification_version: 4
 summary: An API extension to the Blazer gem
-test_files: []
+test_files:
+- spec/spec_helper.rb
+- spec/rails_helper.rb

data/lib/blazer_json_api/config.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module BlazerJsonAPI
-  class Config
-    # defaults
-    @@nesting_column_separator = '__'
-
-    cattr_accessor :username
-    cattr_accessor :password
-    cattr_accessor :nesting_column_separator
-  end
-end