apicasso 0.2.7 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5bb7e923ec8a2c1b6dd39fa43f73aa1be3ee06e8
-  data.tar.gz: bb00637db4132d6657dd28522dd44ecb5c4aab66
+  metadata.gz: f4a2ce3d41ad82b4b1ac28fc6dfa0b6f8a756b55
+  data.tar.gz: 8d1d9d6f5aa7abae2406020e6445d1e3b1bb3932
 SHA512:
-  metadata.gz: b40b4cd7847667e72ec02688ff615fd0c5478d00fb61428423c99e10a25b12c19f2ee6c1cfdad9bdb3b003e63e372f909448efcc42647a1bfd454075f139b27c
-  data.tar.gz: 066b338bbb39d787213ad8d836ccaa24a72b8bf1934c86dc9ab1d468eada1450f7715b37908627b7ebd60c2feb7512568d85b0305e41e2b022e556c572d5e5eb
+  metadata.gz: 02332ef2f6cb186bfb2f94f88ad44d60341fb6fff892ffac77293474bd3089ba297b48b6934f6d89d1fd3d773ccc4f5b8f7754e597a58b83fee4fb06728e5ff3
+  data.tar.gz: 9a45a1ac48bb74da7bc40aa003a9faf0d0da486f89b9c9f66ca47732d25a80bfb0f6d74347e5eab1d25983c50f91eaa5330bcb9716c6dfb5a330ef4dced02444

data/README.md

@@ -5,7 +5,7 @@ JSON API development can get boring and time consuming. If you think it through,
 **APIcasso** is intended to be used as a full-fledged CRUD JSON API or as a base controller to speed-up development.
 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
+# Installation
 Add this line to your application's `Gemfile`:
 
 ```ruby
@@ -18,8 +18,13 @@ $ rails g apicasso:install
 ```
 You will need to use a database with JSON fields support to use this gem.
 
-## Usage
-After installing APIcasso into your application 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`:
+# Usage
+
+**APIcasso** is meant to be used as an engine, which means you don't need to configure any route or controller to build a working CRUD API. Sometimes you also need some customized controller actions or even a specific logic to access some of your application's resources. In that case you will use `Apicasso::CrudController` class to easily build only your own logic around the API abstraction.
+
+## 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"
@@ -39,47 +44,116 @@ Your API will reflect very similarly a `resources :resource` statement with the
   options '/:resource/' # A schema dump for the required `:resource`
   options '/:resource/:id/:nested/' # A schema dump for the required `:nested` relation from one of your application's `:resource`
 ```
+
 This means all your application's models will be exposed as `:resource` and it's relations will be exposed as `:nested`. It will enable you to CRUD and get schema metadata from your records.
 
- > But this is permissive as hell! I do not want to expose my entire application like this, haven't you thought about security?
+## Authorization/Authentication
+
+ > But exposing my models to de internet is permissive as hell! Haven't you thought about security?
 
-*Sure!* The API is being exposed 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).
 
-Your API is then exposed based on each `Apicasso::Key.scope` definition
+Each `Apicasso::Key` object has a token attribute, which is used to define the authorized access identification.
+
+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:
                             [{ order: true }, { user: { account_id: 1 } }],
                           read:
-                            [{ account: { id: 1 } }]
+                            [{ account: { manager_id: 1 } }]
                         })
 ```
-This translates directly into which parts of your application is exposed to each APIcasso keys.
+> 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`.
 
-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.
 
-This saves you the trouble of having to setup each and every controller for each model. And even if your application really need it, just make your controllers inherit from `Apicasso::CrudController` and extend it's functionalities. This authorization feature is why one of the dependencies for this gem is [CanCanCan](https://github.com/CanCanCommunity/cancancan), that abstracts the scope field into authorization for your application's resources.
+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. A scope as `{ read: [{ account: { manager_id: 1 } }] }` will have read access into accounts with `manager_id == 1`
 
-The `crud#index` and `crud#nested_index` actions are already equipped with pagination, ordering and filtering.
+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` will extend it's functionalities, enabling the use of `@object` and `@resource` variables to access what is being resquested.
 
- - You can pass `params[:sort]` with field names preffixed with `+` or `-` to configure custom ordering per request. I.E.: `?sort=+updated_at,-name`
- - You can pass `params[:q]` using [ransack's search matchers](https://github.com/activerecord-hackery/ransack#search-matchers) to build a search query. I.E.: `?q[full_name_start]=Picasso`
- - You can pass `params[:page]` and `params[:per_page]` to build pagination options. I.E.: `?page=2&per_page=12`
+## Features on index actions
 
-## 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/).
+The index actions present in the gem are already equipped with pagination, ordering, grouping, fieldset selection and filtering. This will save you a lot of trouble, adding some best-practices conventions into your application's API.
 
-## License
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+### Sort
 
-## 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).
+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
+```
+
+### 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,
+  total_pages: 102,
+  last_page: false,
+  previous_page: localhost:3000/my_records?page=1&per_page=12,
+  next_page: localhost:3000/my_records?page=3&per_page=12,
+  out_of_bounds: false,
+  offset: 12 }
+```
+
+### Fieldset selecting
+
+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.
+
+### 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
+
+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.
+
+# 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 features into README: fieldset selection, grouping responses, infinite collections, auto-documentation
+ - 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/crud_controller.rb

@@ -147,7 +147,7 @@ module Apicasso
     # or a grouped count of attributes
     def index_json
       if params[:group].present?
-        accessible_records.group(params[:group].split(',')).count
+        accessible_records.group(params[:group][:by].split(',')).send(params[:group][:calculate], params[:group][:fields])
       else
         collection_response
       end
@@ -170,7 +170,7 @@ module Apicasso
 
     # Returns the collection checking if it needs pagination
     def collection_response
-      if params[:per_page].to_i == -1
+      if params[:per_page].to_i < 0
         built_unpaginated
       else
         built_paginated

data/lib/apicasso/version.rb

@@ -1,3 +1,3 @@
 module Apicasso
-  VERSION = '0.2.7'
+  VERSION = '0.2.8'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apicasso
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.2.8
 platform: ruby
 authors:
 - Fernando Bellincanta
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-27 00:00:00.000000000 Z
+date: 2018-08-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cancancan