json_apiable 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0527cb82ea3c0689d6086d1728291e77bff1cd94da969953b8965e729eb66b6
-  data.tar.gz: e98ff51f719ca22f14574c9acdb4a8b1175e13d513b8f93f2595d4d83cdffa89
+  metadata.gz: 02ceaeecfcdb306933da14c8f4596e355958a6bd6902dc37a365295e409d085e
+  data.tar.gz: b5dc5338fcb3cd7fd1991f4dc18871ffdc3ed4d63c99d0e826469b558dba8dc0
 SHA512:
-  metadata.gz: c424b59b59efa76d8f04c248345ce5a42b9c2b2f53bf539a73f0eea4e4b4551186f32c8923fc097182c54e123582e9a4bdfdf7a715e5417de724bbe485715715
-  data.tar.gz: 73af3e75acfb6a3e8a69fafdb338882cbcd2e6bcc38d5b9e65600ee5824b7af98ae650e38ec8520fe9b1f38a2591d34652081a18e3d1df1d977c072c5ecfdc48
+  metadata.gz: 5c5ddc873cee6e321ab133f8422d22dfe3cc2c46ae57af5c2a1bbfc9b759e00c50b333e11af758ef80f89c8f1b1a5edcbbbd8edb2dd79c13f4659ae20e8a5d4a
+  data.tar.gz: 8e9cbdf0d269a0682b2f863b50fdcc71ed00a991174be19d293d75463578cada37390254d45d7a389b6447ece782d6c922b9bef79bc8d9518ede3bbbbf24188f

data/.gitignore

@@ -13,3 +13,5 @@
 # rspec failure tracking
 .rspec_status
 /spec/support/rails_app/db/*.sqlite3
+/spec/support/rails_app/tmp/
+/spec/support/rails_app/log/

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    json_apiable (0.1.0)
+    json_apiable (0.2.0)
       activerecord (>= 4.2)
       activesupport (>= 4.2)
       fast_jsonapi (~> 1.5)
@@ -186,7 +186,7 @@ DEPENDENCIES
   rails
   rails-controller-testing
   rake (~> 10.0)
-  rspec-rails
+  rspec-rails (~> 3.9)
   sqlite3
 
 BUNDLED WITH

data/README.md

@@ -1,8 +1,10 @@
 # JsonApiable
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/json_apiable`. To experiment with that code, run `bin/console` for an interactive prompt.
+JsonApiable is a Ruby module that makes it easier for Rails API controllers to handle JSON:API parameter and relationship parsing,
+strong parameter validation, returning well-structured errors and more - all in a Rails-friendly way.
 
-TODO: Delete this and the text above, and describe your gem
+JsonApiable doesn't assume anything about other JSON:API gems you may be using. 
+Feel free to use it in conjunction with fast_jsonapi, active_model_serializer, jsonapi-resources or any other library.
 
 ## Installation
 
@@ -21,8 +23,137 @@ Or install it yourself as:
     $ gem install json_apiable
 
 ## Usage
+### Basics
+```ruby
+# include JsonApiable in your Base API controller
+class API::BaseController < ActionController::Base
+  # By including JsonApiable, you get the following before/after actions in your controllers:
+  # 
+  # before_action :ensure_jsonapi_content_type       - Ensure correct Content-Type (application/vnd.api+json) is set in 
+  #                                                    the request, and return error othewrise 
+  # before_action :ensure_jsonapi_valid_query_params - Ensure only valid query parameters are used
+  # before_action :parse_jsonapi_pagination          - Parse "?page:{number:1, size:25}" query hash, set defaults and 
+  #                                                    return errors when invalid values received
+  #                                                    Read more: https://jsonapi.org/format/#fetching-pagination 
+  # before_action :parse_jsonapi_include             - Parse "?include=posts.author" include directives . 
+  #                                                    Read more: https://jsonapi.org/format/#fetching-includes
+  # after_action :set_jsonapi_content_type           - Ensure correct Content-Type (application/vnd.api+json) is set 
+  #                                                    in the response
+  
+  # By including JsonApiable, you get the following exceptions handled automatically:
+  # rescue_from ArgumentError
+  # rescue_from ActionController::UnpermittedParameters
+  # rescue_from MalformedRequestError
+  # rescue_from UnprocessableEntityError
+  # rescue_from ActiveRecord::RecordNotFound
+  include JsonApiable
+end
+
+class API::PostsController < API::BaseController
+  
+  # GET /v1/posts
+  def index
+    # pass page and include info to your logic
+    posts = GetPostsService.call(jsonapi_page, jsonapi_include)
+    # some other gem, such as fast_jsonapi is assumed to produce the json:api output
+    render json: posts
+  end
+
+  # PATCH /v1/posts/123/update
+  # { "data":
+  #    { "type": "post",
+  #      "attributes": {
+  #         "title": "My New Title"
+  #      },
+  #      "relationships": {
+  #         "author": {
+  #            "data": {
+  #                 "type": "user",
+  #                 "id": "4528"
+  #            },
+  #           "comments": {
+  #             "data": [
+  #               { "type": "comment", "id": "1489" },
+  #               { "type": "comment", "id": "1490" } 
+  #             ] 
+  #           } 
+  #         }
+  #        } 
+  #     } 
+  # }
+  def update
+    @post = Post.find(params[:id])
+
+    # turn relationships into Rails associations and assign them together with attributes 
+    # as you would normally do in Rails
+    # 
+    # jsonapi_assign_params =>
+    # { "title"=>"My New Title",
+    #   "author_id" => 4528, 
+    #   "comments_attributes"=>{
+    #         "0"=>{"id"=>"1489", "_destroy"=>"false"}, 
+    #         "1"=>{"id"=>"1490", "_destroy"=>"false"}},
+    #   "comment_ids"=>["1489", "1490"],
+    # 
+    # } 
+    @post.update_attributes!(jsonapi_assign_params)
+    render json: @user
+  end
+
+  def create
+    # use jsonapi_attribute_present? to quickly test presence of specific attributes
+    raise UnprocessableEntityError, 'No title!' unless jsonapi_attribute_present?(:title)
+    # use jsonapi_attribute_value to get attribute values. If non-existent, nil would be returned
+    @title = jsonapi_attribute_value(:title)
+    # exclude 'author' attribute from assign params, for example because it's a separate table on the DB level)
+    @author_name = jsonapi_exclude_attribute(:author_name)
+    # exclude 'comments' relationship from assign params, for example because we want to filter which ones are added to post
+    @comments_hash = jsonapi_exclude_relationship(:comments)
+    do_some_logc_with_excluded_params
+    # jsonapi_assign_params wouldn't include 'author' attribute and 'comments' relationship
+    User.create!(jsonapi_assign_params)
+  end
+
+  protected
+
+  # declare which attributes should be allowed to be assigned. Complex attributes are allowed
+  def jsonapi_allowed_attributes
+    [:title,
+     :body,
+     dates: %i[first_drafted published last_edited]]
+  end
+
+  # declare which relationships should be allowed to be assigned
+  def jsonapi_allowed_relationships
+    %i[comments contributors]
+  end
+
+
+
+end
+````
+### Configuration
+Add an initializer to your app with the following config block:
+```ruby
+JsonApiable.configure do |config|
+  # white-list query params that should be allowed
+  config.valid_query_params = %w[ id access_token user_id organization_id ]
+
+  # by default, error is returned if the request Content-Type isn't valid JSON-API. Override the behaviour by using this block:
+  config.supported_media_type_proc = proc do |request|
+    request.content_type == JsonApiable::JSONAPI_CONTENT_TYPE || request.headers['My-Special-Header'].present?
+  end
+
+  # by default, ActiveRecord::RecordNotFound is caught by JsonApiable and turned into an error response. If your backend raises a different class of exception, set it here
+  config.not_found_exception_class = MyExceptionClass
+
+end
+```
 
-TODO: Write usage instructions here
+### Limitations
+- `has_one` associations are currently not supported by `jsonapi_assign_params`. So if the updated resource
+contains an association whose foreign key exists in
+- complex attributes currently don't work
 
 ## Development
 

data/json_apiable.gemspec

@@ -36,6 +36,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'rails'
   spec.add_development_dependency 'rails-controller-testing'
   spec.add_development_dependency 'rake', '~> 10.0'
-  spec.add_development_dependency 'rspec-rails'
+  spec.add_development_dependency 'rspec-rails', '~> 3.9'
   spec.add_development_dependency 'sqlite3'
 end

data/lib/json_apiable/configuration.rb

@@ -8,7 +8,7 @@ module JsonApiable
     MAX_PAGE_SIZE = 214_748_364
 
     def initialize
-      @valid_query_params = %w[id access_token filter include page]
+      @valid_query_params = %w[id user_id access_token filter include page]
       @supported_media_type_proc = nil
       @not_found_exception_class = ActiveRecord::RecordNotFound
       @page_size = DEFAULT_PAGE_SIZE

data/lib/json_apiable/json_apiable.rb

@@ -9,12 +9,12 @@ module JsonApiable
               :jsonapi_exclude_attributes, :jsonapi_exclude_relationships
 
   included do
-    before_action :ensure_content_type
-    before_action :ensure_valid_query_params
-    before_action :parse_pagination
-    before_action :parse_include
+    before_action :ensure_jsonapi_content_type
+    before_action :ensure_jsonapi_valid_query_params
+    before_action :parse_jsonapi_pagination
+    before_action :parse_jsonapi_include
 
-    after_action :set_content_type
+    after_action :set_jsonapi_content_type
 
     rescue_from ArgumentError, with: :respond_to_bad_argument
     rescue_from ActionController::UnpermittedParameters, with: :respond_to_bad_argument
@@ -46,6 +46,10 @@ module JsonApiable
     jsonapi_build_params.dig(:data, :attributes, attrib_key).present?
   end
 
+  def jsonapi_attribute_value(attrib_key)
+    jsonapi_build_params.dig(:data, :attributes, attrib_key)
+  end
+
   def jsonapi_assign_params
     @jsonapi_assign_params ||= ParamsParser.parse_body_params(request,
                                                               jsonapi_build_params,
@@ -87,11 +91,11 @@ module JsonApiable
     %i[]
   end
 
-  def ensure_content_type
+  def ensure_jsonapi_content_type
     respond_to_unsupported_media_type unless supported_media_type?
   end
 
-  def ensure_valid_query_params
+  def ensure_jsonapi_valid_query_params
     invalid_params = request.query_parameters.keys.reject { |k| JsonApiable.configuration.valid_query_params.include?(k) }
     respond_to_bad_argument(invalid_params.first) if invalid_params.present?
   end
@@ -104,15 +108,15 @@ module JsonApiable
     end
   end
 
-  def set_content_type
+  def set_jsonapi_content_type
     response.headers['Content-Type'] = JSONAPI_CONTENT_TYPE
   end
 
-  def parse_pagination
+  def parse_jsonapi_pagination
     @jsonapi_page = PaginationParser.parse_pagination!(query_params, jsonapi_default_page_size)
   end
 
-  def parse_include
+  def parse_jsonapi_include
     @jsonapi_include = query_params[:include].presence&.gsub(/ /, '')&.split(',')&.map(&:to_sym).to_a
   end
 

data/lib/json_apiable/version.rb

@@ -1,3 +1,3 @@
 module JsonApiable
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: json_apiable
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Mike Polischuk
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-01-06 00:00:00.000000000 Z
+date: 2020-01-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -168,16 +168,16 @@ dependencies:
   name: rspec-rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.9'
 - !ruby/object:Gem::Dependency
   name: sqlite3
   requirement: !ruby/object:Gem::Requirement