schema_based_api 2.1.14 → 2.1.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8471d0089a6858a8fc54493fcd2e1d10ec3cf82d021ed347645dc999c1e0ec5e
-  data.tar.gz: cfac408c1ffdff059610eaa98aa40e093705c74f74953f886abb792f622c2ac4
+  metadata.gz: f096bb076a59df02a1c9a51b348a4265b4c4bcc085ee17297873b31cafdfe70a
+  data.tar.gz: 27a50ee08425905661fd685c4c5fed9619f2e86ca78aa510a1d18b749694452c
 SHA512:
-  metadata.gz: 1695890938108ed0b87b9334c945bd6277a9784934ef6c9bab9a5def8d82aac2a49fb1f2cd649f67aeec2425b226a24767413418999ab745a3d1e822e8222646
-  data.tar.gz: ad5835d2ff8a1fcd14cb4b4e49400401cab586283d874c6fe83c54c1c0a40f68574aa089bef8116041a3287d1f65d9da873a08e641f4fd414bf1df66f3404065
+  metadata.gz: 9bfceb05a06565d3896d4cf3cdfdffe2b99c99e034f4879cf8a83d75c15f283211ee59e7e956ad60080f52aa51a0e45f5a35cd8ca021ff9ccc829dbf5b1a9df1
+  data.tar.gz: 1ddf3166f10c7e884081ed873f926ad25ca60e5382690a5a391b13777223616189184c8bb97b11047e7e1e1ea01839e27860632dd0a0d51dceeed39f763ffb5f

data/README.md

@@ -50,11 +50,152 @@ This will setup a User model, Role model and the HABTM table between the two.
 Then, if you fire up your ```rails server``` you can already get a jwt and perform different operations.
 The default admin user created during the migration step has a randomly generated password you can find in a .passwords file in the root of your project, that's the initial password, in production you can replace that one, but for testing it proved handy to have it promptly available.
 
+## Consuming the API
+
+### Getting the Token
+
+The first thing that must be done by the client is to get a Token using the credentials:
+
+```bash
+POST http://localhost:3000/api/v2/authenticate
+```
+
+with a POST body like the one below:
+
+```json
+{
+	"auth": {
+		"email": "<REPLACE>",
+		"password": "<REPLACE>"
+	}
+}
+```
+
+This action will return in the header a *Token* you can use for the following requests.
+Bear in mind that the *Token* will expire within 15 minutes and that at each succesful request a new token is returned using the same *Token* header, so, at each interaction between client server, just making an authenticated and succesful request, will give you back a way of continuing to make authenticated requests without the extra overhead of an authentication for each one and without having to keep long expiry times for the *Token*.
+
+### Info API
+
+The info API **api/v2/info/** can be used to retrieve general information about the REST API:
+
+#### Version
+
+By issuing a GET on this api, you will get a response containing the version of the schema_based_api. 
+This is a request which doesn't require authentication, it could be used as a checkpoint for consuming the resources exposed by this engine.
+
+```bash
+GET http://localhost:3000/api/v2/info/version
+```
+
+Would produce a response body like this one:
+
+```json
+{
+  "version": "2.1.14"
+}
+```
+
+#### Roles
+
+**Authenticated Request** by issuing a GET request to */api/v2/info/roles*:
+
+```bash
+GET http://localhost:3000/api/v2/info/roles
+```
+
+Something like this can be retrieved:
+
+```json
+[
+  {
+    "id": 1,
+    "name": "role-1586521657646",
+    "created_at": "2020-04-10T12:27:38.061Z",
+    "updated_at": "2020-04-10T12:27:38.061Z",
+    "lock_version": 0
+  },
+  {
+    "id": 2,
+    "name": "role-1586522353509",
+    "created_at": "2020-04-10T12:39:14.276Z",
+    "updated_at": "2020-04-10T12:39:14.276Z",
+    "lock_version": 0
+  }
+]
+```
+
+#### Schema
+
+**Authenticated Request** This action will send back the *authorized* models accessible by the current user at least for the [:read ability](https://github.com/ryanb/cancan/wiki/checking-abilities). The list will also show the field types of the model and the associations.
+
+By issuing this GET request:
+
+```bash
+GET http://localhost:3000/api/v2/info/roles
+```
+
+You will get something like:
+
+```json
+{
+  "users": {
+    "id": "integer",
+    "email": "string",
+    "encrypted_password": "string",
+    "admin": "boolean",
+    "lock_version": "integer",
+    "associations": {
+      "has_many": [
+        "role_users",
+        "roles"
+      ],
+      "belongs_to": []
+    },
+    "methods": null
+  },
+  "role_users": {
+    "id": "integer",
+    "created_at": "datetime",
+    "updated_at": "datetime",
+    "associations": {
+      "has_many": [],
+      "belongs_to": [
+        "user",
+        "role"
+      ]
+    },
+    "methods": null
+  },
+  "roles": {
+    "id": "integer",
+    "name": "string",
+    "created_at": "datetime",
+    "updated_at": "datetime",
+    "lock_version": "integer",
+    "associations": {
+      "has_many": [
+        "role_users",
+        "users"
+      ],
+      "belongs_to": []
+    },
+    "methods": null
+  }
+}
+```
+
+The *methods* key will list the **custom actions** that can be used in addition to normal CRUD operations, these can be bulk actions and anything that can serve a purpose, usually to simplify the interaction between client and server (i.e. getting in one request the result of a complex computations which usually would be sorted out using more requests). Later on this topic.
+
 ## Testing
 
-If you want to manually test the API using [Insomnia](https://insomnia.rest/) I will publish in the repository the export for the chained requests I'm using.
+If you want to manually test the API using [Insomnia](https://insomnia.rest/) you can find the chained request in Insomnia v4 json format inside the **test/insomnia** folder.
 In the next few days, I'll publish also the rspec tests.
 
+## TODO
+
+* Integrate a settings gem
+* Add DSL for users and roles
+
 ## References
 THanks to all these people for ideas:
 

data/app/controllers/api/v2/application_controller.rb

@@ -1,21 +1,15 @@
 class Api::V2::ApplicationController < ActionController::API
+    # For the DSL part
     include ActiveHashRelation
-    
-    before_action :authenticate_request
-    before_action :extract_model
-    before_action :find_record, only: [ :show, :destroy, :update ]
-    
-    attr_accessor :current_user
-    
     # Actions will be authorized directly in the action
     include CanCan::ControllerAdditions
-
     include ::ApiExceptionManagement
+
+    attr_accessor :current_user
     
-    # Nullifying strong params for API
-    def params
-        request.parameters
-    end
+    before_action :authenticate_request
+    before_action :extract_model
+    before_action :find_record, only: [ :show, :destroy, :update ]
     
     # GET :controller/
     def index
@@ -109,8 +103,11 @@ class Api::V2::ApplicationController < ActionController::API
         # or
         # [GET|PUT|POST|DELETE] :controller/:id?do=:custom_action
         unless params[:do].blank?
-            raise NoMethodError unless @model.respond_to?(params[:do])
-            return true, MultiJson.dump(params[:id].blank? ? @model.send(params[:do], params) : @model.send(params[:do], params[:id].to_i, params))
+            # Poor man's solution to avoid the possibility to 
+            # call an unwanted method in the AR Model.
+            resource = "custom_action_#{params[:do]}"
+            raise NoMethodError unless @model.respond_to?(resource)
+            return true, MultiJson.dump(params[:id].blank? ? @model.send(resource, params) : @model.send(resource, params[:id].to_i, params))
         end
         # if it's here there is no custom action in the request querystring
         return false
@@ -119,7 +116,8 @@ class Api::V2::ApplicationController < ActionController::API
     def authenticate_request
         @current_user = AuthorizeApiRequest.call(request.headers).result
         return unauthenticated! unless @current_user
-        params[:current_user] = current_user = @current_user
+        current_user = @current_user
+        params[:current_user_id] = @current_user.id
         # Now every time the user fires off a successful GET request, 
         # a new token is generated and passed to them, and the clock resets.
         response.headers['Token'] = JsonWebToken.encode(user_id: current_user.id)
@@ -148,4 +146,9 @@ class Api::V2::ApplicationController < ActionController::API
         # Only ActiveRecords can have this model caputed 
         return not_found! if (!@model.new.is_a? ActiveRecord::Base rescue false)
     end
+
+    # Nullifying strong params for API
+    def params
+        request.parameters
+    end
 end

data/app/controllers/api/v2/authentication_controller.rb

@@ -9,5 +9,4 @@ class Api::V2::AuthenticationController < ActionController::API
             head :ok
         end
     end
-    
 end

data/config/initializers/after_initialize_for_schema_based_api.rb

@@ -1,7 +1,9 @@
 require 'concerns/schema_based_api_user'
+require 'concerns/schema_based_api_role'
 
 Rails.application.configure do
     config.after_initialize do
         User.send(:include, SchemaBasedApiUser)
+        Role.send(:include, SchemaBasedApiRole)
     end
 end

data/lib/concerns/schema_based_api_role.rb

@@ -0,0 +1,41 @@
+module SchemaBasedApiRole
+    extend ActiveSupport::Concern
+    
+    included do
+        ## DSL (AKA what to show in the returned JSON)
+        # Use @@json_attrs to drive json rendering for 
+        # API model responses (index, show and update ones).
+        # For reference:
+        # https://api.rubyonrails.org/classes/ActiveModel/Serializers/JSON.html
+        # The object passed accepts only these keys:
+        # - only: list [] of model field names in symbol notation to be shown in JSON 
+        #       serialization.
+        # - except: exclude these fields from the JSON serialization, is a list []
+        #        of model field names in symbol notation.
+        # - methods: include the result of some methods defined in the model (virtual
+        #       fields).
+        # - include: include associated models, it's a list [] of hashes {} which also 
+        #       accepts the [:only, :except, :methods, :include] keys.
+        cattr_accessor :json_attrs
+        @@json_attrs = {
+            except: [:lock_version],
+            include: [:users]
+        }
+
+        ## CUSTOM ACTIONS
+        # Here you can add custom actions to be called from the API
+        # The action must return an serializable (JSON) object.
+
+        # Here you can find an example *without* ID, in the API it could be called like this:
+        # GET /api/v2/:controller?do=test&parameter=sample
+        # def self.custom_action_test params=nil
+        #     { test: [ :first, :second, :third ], params: params}
+        # end
+
+        # Here you can find an example *with* ID, in the API it could be called like this:
+        # GET /api/v2/:controller/:id?do=test_with_id&parameter=sample
+        # def self.custom_action_test_with_id id=nil, params=nil
+        #     { test: [ :first, :second, :third ], id: id, params: params}
+        # end
+    end
+end

data/lib/concerns/schema_based_api_user.rb

@@ -5,5 +5,41 @@ module SchemaBasedApiUser
         def authenticate password
             self&.valid_password?(password) ? self : nil
         end
+
+        ## DSL (AKA what to show in the returned JSON)
+        # Use @@json_attrs to drive json rendering for 
+        # API model responses (index, show and update ones).
+        # For reference:
+        # https://api.rubyonrails.org/classes/ActiveModel/Serializers/JSON.html
+        # The object passed accepts only these keys:
+        # - only: list [] of model field names in symbol notation to be shown in JSON 
+        #       serialization.
+        # - except: exclude these fields from the JSON serialization, is a list []
+        #        of model field names in symbol notation.
+        # - methods: include the result of some methods defined in the model (virtual
+        #       fields).
+        # - include: include associated models, it's a list [] of hashes {} which also 
+        #       accepts the [:only, :except, :methods, :include] keys.
+        cattr_accessor :json_attrs
+        @@json_attrs = {
+            except: [:lock_version],
+            include: [:roles]
+        }
+
+        ## CUSTOM ACTIONS
+        # Here you can add custom actions to be called from the API
+        # The action must return an serializable (JSON) object.
+
+        # Here you can find an example *without* ID, in the API it could be called like this:
+        # GET /api/v2/:controller?do=test&parameter=sample
+        # def self.custom_action_test params=nil
+        #     { test: [ :first, :second, :third ], params: params}
+        # end
+
+        # Here you can find an example *with* ID, in the API it could be called like this:
+        # GET /api/v2/:controller/:id?do=test_with_id&parameter=sample
+        # def self.custom_action_test_with_id id=nil, params=nil
+        #     { test: [ :first, :second, :third ], id: id, params: params}
+        # end
     end
 end

data/lib/schema_based_api/version.rb

@@ -1,3 +1,3 @@
 module SchemaBasedApi
-  VERSION = '2.1.14'
+  VERSION = '2.1.15'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: schema_based_api
 version: !ruby/object:Gem::Version
-  version: 2.1.14
+  version: 2.1.15
 platform: ruby
 authors:
 - Gabriele Tassoni
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-04-18 00:00:00.000000000 Z
+date: 2020-04-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -179,6 +179,7 @@ files:
 - config/initializers/wrap_parameters.rb
 - config/routes.rb
 - lib/concerns/api_exception_management.rb
+- lib/concerns/schema_based_api_role.rb
 - lib/concerns/schema_based_api_user.rb
 - lib/json_web_token.rb
 - lib/schema_based_api.rb