apicasso 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d9eab0692116c8e9b6d81f00ae6012ac0125d06e
-  data.tar.gz: d9fbca376a48478b49055e43b5c0b2a51e59893f
+  metadata.gz: ab5b6196d2e1a9675b5b4eca26522f6ff1dabe63
+  data.tar.gz: 1715dc2d29b09e97deba8f41b811709059a3520c
 SHA512:
-  metadata.gz: aed068877154de286f451f0f41d7049d79421af273873ade2544329287cd8727b2e949415cebdcff6d354b76965cdfb205ad2983845cbecee686f7786541437c
-  data.tar.gz: fa8bc7de5e9000216473ceeddc07d4a9ad89ed1d94a470507416a41d8ef1880c728570d224ee09c9e2a695600fa6d559faf17e92c6be50d40eb4288983d8070c
+  metadata.gz: f9a542fe03655f97043183cb6040d0ff92a0d533a337faf43a4a4771cc0ba75e2ce73c2494d98b0c8436b049bcf548ae0e14cdd8ba26ae0a1b42be2f3186f502
+  data.tar.gz: 5ff7a98726754f89f1cf6f50038b2f5c062f49d204626b5dda58da7eb85d08643ddbc0aa0d9c057f5241a3cb47044f6146431be6453159f933464b47c6b49892

data/README.md

@@ -6,6 +6,7 @@ JSON API development can get boring and time consuming. If you think it through,
 It is a route-based resource abstraction using API key scoping. This makes it possible to make CRUD-only applications just by creating functional Rails' models. It is a perfect candidate for legacy Rails projects that do not have an API. Access to your application's resources is managed by a `.scope` JSON object per API key. It uses that permission scope to restrict and extend access.
 
 # Installation
+
 Add this line to your application's `Gemfile`:
 
 ```ruby
@@ -13,9 +14,11 @@ gem 'apicasso'
 ```
 
 And then execute this to generate the required migrations:
+
 ```bash
 $ bundle install && rails g apicasso:install
 ```
+
 You will need to use a database with JSON fields support to use this gem.
 
 # Usage
@@ -25,6 +28,7 @@ You will need to use a database with JSON fields support to use this gem.
 ## Mounting engine into `config/routes.rb`
 
 After installing it, you can mount a full-fledged CRUD JSON API just by attaching into some route. Usually you will have it under a scoped route like `/api/v1` or a subdomain. You can do that by adding this into your `config/routes.rb`:
+
 ```ruby
   # To mount your APIcasso routes under the path scope `/api/v1`
   mount Apicasso::Engine, at: "/api/v1"
@@ -33,7 +37,9 @@ After installing it, you can mount a full-fledged CRUD JSON API just by attachin
     mount Apicasso::Engine, at: "/"
   end
 ```
+
 Your API will reflect very similarly a `resources :resource` statement with the following routes:
+
 ```ruby
   get '/:resource/' # Index action, listing a `:resource` collection from your application
   post '/:resource/' # Create action for one `:resource` from your application
@@ -50,11 +56,14 @@ This means all your application's models will be exposed as `:resource` and it's
 ## Extending base API actions
 
 When your application needs some kind of custom interaction that is not covered by APIcasso's CRUD approach you can make your own actions using our base classes and objects to go straight into your logic. If you have built the APIcasso's engine into a route it is important that your custom action takes precedence over the gem's ones. To do that you need to declare your custom route before the engine on you `config/routes.rb`
+
 ```ruby
   match '/:resource/:id/a-custom-action' => 'custom#not_a_crud', via: :get
   mount Apicasso::Engine, at: "/api/v1"
 ```
+
 And in your `app/controllers/custom_controller.rb` you would have something like:
+
 ```ruby
   class CustomController < Apicasso::CrudController
     def not_a_crud
@@ -62,17 +71,27 @@ And in your `app/controllers/custom_controller.rb` you would have something like
     end
   end
 ```
+
 This way you enjoy all our object finder, authorization and authentication features, making your job more straight into your business logic.
 
-## Authorization/Authentication
+## Authentication
 
- > But exposing my models to the internet is permissive as hell! Haven't you thought about security?
+> But exposing my models to the internet is permissive as hell! Haven't you thought about security?
 
-*Sure!* The **APIcasso** suite is exposing your application using authentication through `Authorization: Token` [HTTP header authentication](http://tools.ietf.org/html/draft-hammer-http-token-auth-01). The API key objects are manageable through the `Apicasso::Key` model, which gets setup at install. When a new key is created a `.token` is generated using an [Universally Unique Identifier(RFC 4122)](https://tools.ietf.org/html/rfc4122).
+_Sure!_ The **APIcasso** suite is exposing your application using authentication through `Authorization: Token` [HTTP header authentication](http://tools.ietf.org/html/draft-hammer-http-token-auth-01). The API key objects are manageable through the `Apicasso::Key` model, which gets setup at install. When a new key is created a `.token` is generated using an [Universally Unique Identifier(RFC 4122)](https://tools.ietf.org/html/rfc4122). A authenticated request looks like this:
 
-Each `Apicasso::Key` object has a token attribute, which is used to define the authorized access identification.
+```
+curl -X GET \
+  https://apixample.com/v1/your_app_resource \
+  -H 'authorization: Token token=cda4e9f633c123ef9ddce5e6564292b3'
+```
+
+Each `Apicasso::Key` object has a token attribute, which is used on this header to authorize access. For now, there is no plans for a login/JWT logic, you should implement this in your project's scope.
+
+## Authorization
 
 Your Models are then exposed based on each `Apicasso::Key.scope` definition, which is a way to configure how much of your application each key can access. I.E.:
+
 ```ruby
   Apicasso::Key.create(scope:
                         { manage:
@@ -81,13 +100,15 @@ Your Models are then exposed based on each `Apicasso::Key.scope` definition, whi
                             { account: { manager_id: 1 } }
                         })
 ```
+
 > The key from this example will have full access to all orders and to users with `account_id == 1`. It will have also read-only access to accounts with `id == 1`.
 
-A scope configured like this translates directly into which kind of access each key has on all  of your application's models. This kind of authorization is why one of the dependencies for this gem is [CanCanCan](https://github.com/CanCanCommunity/cancancan), which abstracts the scope field into your API access control.
+A scope configured like this translates directly into which kind of access each key has on all of your application's models. This kind of authorization is why one of the dependencies for this gem is [CanCanCan](https://github.com/CanCanCommunity/cancancan), which abstracts the scope field into your API access control.
 
 You can have two kind of access control:
- * `true` - This will mean the key will have the declared clearance on **ALL** of this model's records
- * `Hash` - This will build a condition to what records this key have access to. A scope as `{ read: [{ account: { manager_id: 1 } }] }` will have read access into accounts with `manager_id == 1`
+
+- `true` - This will mean the key will have the declared clearance on **ALL** of this model's records
+- `Hash` - This will build a condition to what records this key have access to. A scope as `{ read: [{ account: { manager_id: 1 } }] }` will have read access into accounts with `manager_id == 1`
 
 This saves you the trouble of having to setup every controller for each model. And even if your application really needs it, just make your controllers inherit from `Apicasso::CrudController` extending it and enabling the use of `@object` and `@resource` variables to access what is being resquested.
 
@@ -100,6 +121,7 @@ The index actions present in the gem are already equipped with pagination, order
 You can sort a collection query by using a URL parameter with field names preffixed with `+` or `-` to configure custom ordering per request.
 
 To order a collection with ascending `updated_at` and descending `name` you can add the `sort` parameter with those fields as options, indicating which kind of ordination you want to give to each one:
+
 ```
 ?sort=+updated_at,-name
 ```
@@ -107,18 +129,23 @@ To order a collection with ascending `updated_at` and descending `name` you can
 ### Filtering/Search
 
 APIcasso has [ransack's search matchers](https://github.com/activerecord-hackery/ransack#search-matchers) on it's index actions. This means you can dynamically build search queries with any of your resource's fields, this will be done by using a `?q` parameter which groups all your filtering options on your requests. If you wanted to search all your records and return only the ones with `full_name` starting with `Picasso` your query would look something like this:
+
 ```
 ?q[full_name_start]=Picasso
 ```
+
 To build complex search queries you can chain many parameter options or check [ransack's wiki](https://github.com/activerecord-hackery/ransack/wiki/) on how to adapt this feature into your project's needs.
 
 ### Pagination
 
 Automatic pagination is done in index actions, with the adittion of some metadata to help on the data consumption. You can pass page and per page parameters to build pagination options into your needs. And on requests that you need unpaginated collections, just pass a lower than zero `per_page`. Example of a pagination query string:
+
 ```
 ?page=2&per_page=12
 ```
+
 Your colletion will be build inside a JSON along with some metadata about it. The response structure is:
+
 ```
 { entries: [{Record1}, {Record2}, {Record3} ... {Record12}],
   total: 1234,
@@ -134,43 +161,62 @@ Your colletion will be build inside a JSON along with some metadata about it. Th
 
 Sometimes your data can grow large in some tables and you need to consumed only a limited set of data on a given frontend application. To avoid large requests and filtering a lot of unused data with JS you can restrict which fields you need on your API's reponse. This is done adding a `?select` parameter. Just pass the field names you desire splitted by `,`
 Let's say you are building a user list with their name, e-mails and phones, to get only those fields your URL query would look something like:
+
 ```
 ?select=name,email,phone
 ```
-This will change the response to filter out the unwanted attributes.
+
+This will change the response to return only the requested attributes. You need to observe that your business logic may require some fields for a valid response to be returned. **This method can be used both on index and show actions**
+
+### Including relations or methods on response
+
+If there is any method or relation that you want to be inserted on the payload, you just need to pass them as a part of the URL query like this:
+
+```
+?include=pictures,suggestions
+```
+
+This will insert the contents of `.pictures` and `.suggestions` on the payload, along with the records' data. **This method can be used both on index and show actions**
 
 ### Grouping operations
 
 If you need to make grouping calculations, like:
- * Counting of all records, or by one **optional** field presence
- * Maximum value of one field
- * Minimum value of one field
- * Average value of one field
- * Value sum of one field
+
+- Counting of all records, or by one **optional** field presence
+- Maximum value of one field
+- Minimum value of one field
+- Average value of one field
+- Value sum of one field
 
 Grouping is done by the combination of 3 parameters
+
 ```
 ?group[by]=a_field&group[calculate]=count&group[fields]=another_field
 ```
+
 Each of those attributes on the `?group` parameter represent an option of the query being made.
- - `group[by]` - Represents which field will be the key for the grouping behavior
- - `group[calculate]` - Which calculation will be sent in the response. Options are: `count`, `maximum`, `minimum`, `average`, `sum`
- - `group[fields]` - Represents which field will be the base for the response calculation.
+
+- `group[by]` - Represents which field will be the key for the grouping behavior
+- `group[calculate]` - Which calculation will be sent in the response. Options are: `count`, `maximum`, `minimum`, `average`, `sum`
+- `group[fields]` - Represents which field will be the base for the response calculation.
 
 # Contributing
+
 Bug reports and pull requests are welcome on GitHub at https://github.com/ErvalhouS/APIcasso. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant code of conduct](http://contributor-covenant.org/). To find good places to start contributing, try looking into our issue list and our Codeclimate profile, or if you want to participate actively on what the core team is working on checkout our todo list:
 
 ### TODO
 
- - Abstract a configurable CORS approach, maybe using middleware.
- - Add gem options like: Token rotation, Alternative authentication methods
- - Add latest auto-documentation feature into README
- - Rate limiting
- - Testing suite
- - Travis CI
+- Abstract a configurable CORS approach, maybe using middleware.
+- Add gem options like: Token rotation, Alternative authentication methods
+- Add latest auto-documentation feature into README
+- Rate limiting
+- Testing suite
+- Travis CI
 
 # Code of conduct
+
 Everyone interacting in the APIcasso project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/ErvalhouS/APIcasso/blob/master/CODE_OF_CONDUCT.md).
 
 # License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/app/controllers/apicasso/application_controller.rb

@@ -1,39 +1,53 @@
 # frozen_string_literal: true
 
 module Apicasso
-  # Controller to extract common API features,
-  # such as authentication and authorization
+  # Controller to extract common API features, such as authentication and
+  # authorization. Used to be inherited by non-CRUD controllers when your
+  # application needs to create custom actions.
   class ApplicationController < ActionController::API
     include ActionController::HttpAuthentication::Token::ControllerMethods
     prepend_before_action :restrict_access, unless: -> { preflight? }
     before_action :set_access_control_headers
     after_action :register_api_request
 
-    # Sets the authorization scope for the current API key
+    # Sets the authorization scope for the current API key, it's a getter
+    # to make scoping easier
     def current_ability
       @current_ability ||= Apicasso::Ability.new(@api_key)
     end
 
     private
 
-    # Identifies API key used in the request, avoiding unauthenticated access
+    # Identifies API key used in the request, avoiding unauthenticated access.
+    # Responds with status 401 when token is not present or not found.
+    # Access restriction happens on the `Authentication` HTTP header.
+    # Example:
+    #   curl -X GET http://example.com/objects -H 'authorization: Token token=f1e048a0b0ef4071a9a64ceecd48c64b'
     def restrict_access
       authenticate_or_request_with_http_token do |token, _options|
-        @api_key = Apicasso::Key.find_by!(token: token)
+        @api_key = Apicasso::Key.find_by(token: token)
       end
     end
 
     # Creates a request object in databse, registering the API key and
-    # a hash of the request and the response
+    # a hash of the request and the response. It's an auditing proccess,
+    # all relevant information about the requests and it's reponses get
+    # recorded within the `Apicasso::Request`. This method assumes that
+    # your project is using some kind of ActiveRecord extension with a
+    # `.delay` method, which when not present makes your API very slow.
     def register_api_request
       Apicasso::Request.delay.create(api_key_id: @api_key.try(:id),
-                                     object: { request: request_hash,
-                                               response: response_hash })
+                                     object: { request: request_metadata,
+                                               response: response_metadata })
+    rescue NoMethodError
+      Apicasso::Request.create(api_key_id: @api_key.try(:id),
+                               object: { request: request_metadata,
+                                         response: response_metadata })
     end
 
-    # Request data built as a hash.
-    # Returns UUID, URL, HTTP Headers and origin IP
-    def request_hash
+    # Information that gets inserted on `register_api_request` as auditing data
+    # about the request. Returns a Hash with UUID, URL, HTTP Headers and IP
+    def request_metadata
       {
         uuid: request.uuid,
         url: request.original_url,
@@ -42,30 +56,34 @@ module Apicasso
       }
     end
 
-    # Resonse data built as a hash.
-    # Returns HTTP Status and request body
-    def response_hash
+    # Information that gets inserted on `register_api_request` as auditing data
+    # about the response sent back to the client. Returns HTTP Status and request body
+    def response_metadata
       {
         status: response.status,
         body: (response.body.present? ? JSON.parse(response.body) : '')
       }
     end
 
-    # Used to avoid errors parsing the search query,
-    # which can be passed as a JSON or as a key-value param
+    # Used to avoid errors parsing the search query, which can be passed as
+    # a JSON or as a key-value param. JSON is preferred because it generates
+    # shorter URLs on GET parameters.
     def parsed_query
       JSON.parse(params[:q])
     rescue JSON::ParserError, TypeError
       params[:q]
     end
 
-    # Used to avoid errors in included associations parsing
+    # Used to avoid errors in included associations parsing and to enable a
+    # insertion point for a change on splitting method.
     def parsed_include
       params[:include].split(',')
     rescue NoMethodError
       []
     end
 
+    # Used to avoid errors in fieldset selection parsing and to enable a
+    # insertion point for a change on splitting method.
     def parsed_select
       params[:select].split(',')
     rescue NoMethodError
@@ -84,7 +102,7 @@ module Apicasso
         offset: records.offset }
     end
 
-    # Generates a contextualized URL of the next page for this request
+    # Generates a contextualized URL of the next page for the request
     def next_link_for(records)
       uri = URI.parse(request.original_url)
       query = Rack::Utils.parse_query(uri.query)
@@ -93,7 +111,7 @@ module Apicasso
       uri.to_s
     end
 
-    # Generates a contextualized URL of the previous page for this request
+    # Generates a contextualized URL of the previous page for the request
     def previous_link_for(records)
       uri = URI.parse(request.original_url)
       query = Rack::Utils.parse_query(uri.query)
@@ -103,11 +121,15 @@ module Apicasso
     end
 
     # Receives a `:action, :resource, :object` hash to validate authorization
+    # Example:
+    #   > authorize_for action: :read, resource: :object_class, object: :object
     def authorize_for(opts = {})
       authorize! opts[:action], opts[:resource] if opts[:resource].present?
       authorize! opts[:action], opts[:object] if opts[:object].present?
     end
 
+    # @TODO
+    # Remove this in favor of a more controllable aproach of CORS
     def set_access_control_headers
       response.headers['Access-Control-Allow-Origin'] = request.headers["Origin"]
       response.headers['Access-Control-Allow-Methods'] = 'POST, GET, PUT, PATCH, DELETE, OPTIONS'
@@ -116,6 +138,7 @@ module Apicasso
       response.headers['Access-Control-Max-Age'] = '1728000'
     end
 
+    # Checks if current request is a CORS preflight check
     def preflight?
       request.request_method == 'OPTIONS' &&
         !request.headers['Authorization'].present?

data/app/controllers/apicasso/crud_controller.rb

@@ -4,7 +4,7 @@ module Apicasso
   # Controller to consume read-only data to be used on client's frontend
   class CrudController < Apicasso::ApplicationController
     before_action :set_root_resource
-    before_action :set_object, except: %i[index schema create]
+    before_action :set_object, only: %i[show update destroy]
     before_action :set_nested_resource, only: %i[nested_index]
     before_action :set_records, only: %i[index nested_index]
 
@@ -13,11 +13,11 @@ module Apicasso
     # GET /:resource
     # Returns a paginated, ordered and filtered query based response.
     # Consider this
-    # To get all `Channel` sorted by ascending `name` and descending
-    # `updated_at`, filtered by the ones that have a `domain` that matches
-    # exactly `"domain.com"`, paginating records 42 per page and retrieving
-    # the page 42 of that collection. Usage:
-    # GET /sites?sort=+name,-updated_at&q[domain_eq]=domain.com&page=42&per_page=42
+    # To get all `Channel` sorted by ascending `name` , filtered by
+    # the ones that have a `domain` that matches exactly `"domain.com"`,
+    # paginating records 42 per page and retrieving the page 42.
+    # Example:
+    #   GET /sites?sort=+name,-updated_at&q[domain_eq]=domain.com&page=42&per_page=42
     def index
       set_access_control_headers
       render json: index_json
@@ -51,7 +51,7 @@ module Apicasso
                     resource: resource.name.underscore.to_sym,
                     object: @object)
       if @object.destroy
-			  head :no_content, status: :ok
+        head :no_content, status: :ok
       else
         render json: @object.errors, status: :unprocessable_entity
       end
@@ -62,7 +62,7 @@ module Apicasso
 
     # POST /:resource
     def create
-      @object = resource.new(resource_params)
+      @object = resource.new(object_params)
       authorize_for(action: :create,
                     resource: resource.name.underscore.to_sym,
                     object: @object)
@@ -153,7 +153,7 @@ module Apicasso
     # or a grouped count of attributes
     def index_json
       if params[:group].present?
-        @records.group(params[:group][:by].split(',')).send(params[:group][:calculate], params[:group][:fields])
+        @records.group(params[:group][:by].split(',')).send(params[:group][:calculate], params[:group][:fields]||params[:group][:by].split(','))
       else
         collection_response
       end

data/lib/apicasso/version.rb

@@ -1,3 +1,3 @@
 module Apicasso
-  VERSION = '0.3.2'
+  VERSION = '0.3.3'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apicasso
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Fernando Bellincanta
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-09-10 00:00:00.000000000 Z
+date: 2018-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cancancan