haveapi 0.18.2 → 0.19.0

data/lib/haveapi/client_examples/js_client.rb

@@ -51,7 +51,17 @@ api.authenticate("token", {
 END
 
       when :oauth2
-        '// OAuth2 is not supported by HaveAPI JavaScript client.'
+        <<END
+#{init}
+// The JavaScript client must be configured with OAuth2 access token, it does not
+// support the authorization procedure to obtain a new access token.
+var accessToken = {
+  access_token: "the access token"
+};
+
+// The client is authenticated immediately, no need for a callback
+api.authenticate("oauth2", {access_token: accessToken});
+END
       end
     end
 

data/lib/haveapi/client_examples/php_client.rb

@@ -35,7 +35,49 @@ $api->authenticate("token", ["token" => $savedToken]);
 END
 
       when :oauth2
-        '// OAuth2 is not supported by HaveAPI PHP client.'
+        <<END
+// OAuth2 requires session
+session_start();
+
+// Client instance
+#{init}
+// Check if we already have an access token
+if (isset($_SESSION["access_token"])) {
+  // We're already authenticated, reuse the existing access token
+  $api->authenticate("oauth2", ["access_token" => $_SESSION["access_token"]]);
+
+} else {
+  // Follow the OAuth2 authorization process to get an access token using
+  // authorization code
+  $api->authenticate("oauth2", [
+    // Client id and secret are given by the API server
+    "client_id" => "your client id",
+    "client_secret" => "your client secret",
+
+    // This example code should run on the URL below
+    "redirect_uri" => "https://your-client.tld/oauth2-callback",
+
+    // Scopes are specific to the API implementation
+    "scope" => "all",
+  ]);
+
+  $provider = $api->getAuthenticationProvider();
+
+  // We don't have authorization code yet, request one
+  if (!isset($_GET['code'])) {
+    // Redirect the user to the authorization endpoint
+    $provider->requestAuthorizationCode();
+    exit;
+
+  } else {
+    // Request access token using the token endpoint
+    $provider->requestAccessToken();
+
+    // Store the access token in the session
+    $_SESSION['access_token'] = $provider->jsonSerialize();
+  }
+}
+END
       end
     end
 

data/lib/haveapi/context.rb

@@ -1,12 +1,12 @@
 module HaveAPI
   class Context
     attr_accessor :server, :version, :request, :resource, :action, :path, :args,
-                  :params, :current_user, :authorization, :endpoint,
+                  :params, :current_user, :authorization, :endpoint, :resource_path,
                   :action_instance, :action_prepare, :layout
 
     def initialize(server, version: nil, request: nil, resource: [], action: nil,
                   path: nil, args: nil, params: nil, user: nil,
-                  authorization: nil, endpoint: nil)
+                  authorization: nil, endpoint: nil, resource_path: [])
       @server = server
       @version = version
       @request = request
@@ -18,6 +18,7 @@ module HaveAPI
       @current_user = user
       @authorization = authorization
       @endpoint = endpoint
+      @resource_path = resource_path
     end
 
     def resolved_path
@@ -71,6 +72,24 @@ module HaveAPI
       path_for(action, call_path_params(action, obj))
     end
 
+    def path_params_from_args
+      ret = {}
+      return ret if args.nil?
+
+      my_args = args.clone
+
+      path.scan(/\{([a-zA-Z\-_]+)\}/) do |match|
+        path_param = match.first
+        ret[path_param] = my_args.shift
+      end
+
+      ret
+    end
+
+    def action_scope
+      resource_path.map(&:downcase).join('.') + '#' + action.action_name.underscore
+    end
+
     private
     def resolve_arg!(path, arg)
       path.sub!(/\{[a-zA-Z\-_]+\}/, arg.to_s)

data/lib/haveapi/example.rb

@@ -58,15 +58,15 @@ module HaveAPI
     def describe(context)
       if provided?
         {
-            title: @title,
-            comment: @comment,
-            path_params: @path_params,
-            request: filter_input_params(context, @request),
-            response: filter_output_params(context, @response),
-            status: @status.nil? ? true : @status,
-            message: @message,
-            errors: @errors,
-            http_status: @http_status || 200,
+          title: @title,
+          comment: @comment,
+          path_params: @path_params,
+          request: filter_input_params(context, @request),
+          response: filter_output_params(context, @response),
+          status: @status.nil? ? true : @status,
+          message: @message,
+          errors: @errors,
+          http_status: @http_status || 200,
         }
       else
         {}

data/lib/haveapi/hooks.rb

@@ -79,15 +79,15 @@ module HaveAPI
   module Hooks
     INSTANCE_VARIABLE = '@_haveapi_hooks'
 
-    # Register a hook defined by +klass+ with +name+.
-    # +klass+ is an instance of Class, that is class name, not it's instance.
-    # +opts+ is a hash and can have following keys:
-    #   - desc - why this hook exists, when it's called
-    #   - context - the context in which given blocks are called
-    #   - args - hash of block positional arguments
-    #   - kwargs - hash of block keyword arguments
-    #   - initial - hash of initial values
-    #   - ret - hash of return values
+    # Register a hook defined by `klass` with `name`.
+    # @param klass [Class]  an instance of Class, that is class name, not it's instance
+    # @param opts [Hash]
+    # @option opts [String] :desc why this hook exists, when it's called
+    # @option opts [String] :context the context in which given blocks are called
+    # @option opts [Hash] :args hash of block positional arguments
+    # @option opts [Hash] :kwargs hash of block keyword arguments
+    # @option opts [Hash] :initial - hash of initial values
+    # @option opts [Hash] :ret hash of return values
     def self.register_hook(klass, name, opts = {})
       classified = hook_classify(klass)
       opts[:listeners] = []
@@ -101,13 +101,13 @@ module HaveAPI
       @hooks
     end
 
-    # Connect class hook defined in +klass+ with +name+ to +block+.
-    # +klass+ is a class name.
+    # Connect class hook defined in `klass` with `name` to `block`.
+    # `klass` is a class name.
     def self.connect_hook(klass, name, &block)
       @hooks[hook_classify(klass)][name][:listeners] << block
     end
 
-    # Connect instance hook from instance +klass+ with +name+ to +block+.
+    # Connect instance hook from instance `klass` with `name` to `block`.
     def self.connect_instance_hook(instance, name, &block)
       hooks = instance.instance_variable_get(INSTANCE_VARIABLE)
 
@@ -120,11 +120,11 @@ module HaveAPI
       hooks[name][:listeners] << block
     end
 
-    # Call all blocks that are connected to hook in +klass+ with +name+.
+    # Call all blocks that are connected to hook in `klass` with `name`.
     # +klass+ may be a class name or an object instance.
-    # If +where+ is set, the blocks are executed in it with instance_exec.
-    # +args+ is an array of arguments given to all blocks. The first argument
-    # to all block is always a return value from previous block or +initial+,
+    # If `where` is set, the blocks are executed in it with instance_exec.
+    # `args` is an array of arguments given to all blocks. The first argument
+    # to all block is always a return value from previous block or `initial`,
     # which defaults to an empty hash.
     #
     # Blocks are executed one by one in the order they were connected.
@@ -193,17 +193,17 @@ module HaveAPI
   # Classes that define hooks must include this module.
   module Hookable
     module ClassMethods
-      # Register a hook named +name+.
+      # Register a hook named `name`.
       def has_hook(name, opts = {})
         Hooks.register_hook(self.to_s, name, opts)
       end
 
-      # Connect +block+ to registered hook with +name+.
+      # Connect `block` to registered hook with `name`.
       def connect_hook(name, &block)
         Hooks.connect_hook(self.to_s, name, &block)
       end
 
-      # Call all hooks for +name+. see Hooks.call_for.
+      # Call all hooks for `name`. see {Hooks.call_for}.
       def call_hooks(*args, **kwargs)
         Hooks.call_for(self.to_s, *args, **kwargs)
       end
@@ -228,7 +228,7 @@ module HaveAPI
         Hooks.call_for(self.class, name, where, args: args, kwargs: kwargs, initial: initial)
       end
 
-      # Call hooks for different +klass+.
+      # Call hooks for different `klass`.
       def call_hooks_as_for(klass, *args, **kwargs)
         ret = call_instance_hooks_as_for(klass, *args, **kwargs)
 
@@ -236,17 +236,17 @@ module HaveAPI
         call_class_hooks_as_for(klass.class, *args, **kwargs)
       end
 
-      # Call only instance hooks for different +klass+.
+      # Call only instance hooks for different `klass`.
       def call_instance_hooks_as_for(klass, *args, **kwargs)
         Hooks.call_for(klass, *args, **kwargs)
       end
 
-      # Call only class hooks for different +klass+.
+      # Call only class hooks for different `klass`.
       def call_class_hooks_as_for(klass, *args, **kwargs)
         Hooks.call_for(klass, *args, **kwargs)
       end
 
-      # Connect instance level hook +name+ to +block+.
+      # Connect instance level hook `name` to `block`.
       def connect_hook(name, &block)
         Hooks.connect_instance_hook(self, name, &block)
       end

data/lib/haveapi/metadata.rb

@@ -6,7 +6,7 @@ module HaveAPI
 
     def self.describe
       {
-          namespace: namespace
+        namespace: namespace
       }
     end
 

data/lib/haveapi/model_adapter.rb

@@ -2,8 +2,8 @@ module HaveAPI
   # Model adapters are used to automate handling of action
   # input/output.
   #
-  # Adapters are chosen based on the +model+ set on a HaveAPI::Resource.
-  # If no +model+ is specified, ModelAdapters::Hash is used as a default
+  # Adapters are chosen based on the `model` set on a HaveAPI::Resource.
+  # If no `model` is specified, ModelAdapters::Hash is used as a default
   # adapter.
   #
   # All model adapters are based on this class.
@@ -17,7 +17,7 @@ module HaveAPI
         ModelAdapter.adapters << Kernel.const_get(self.to_s)
       end
 
-      # Returns an adapter suitable for +layout+ and +obj+.
+      # Returns an adapter suitable for `layout` and `obj`.
       # Adapters are iterated over and the first to return true to handle?()
       # is returned.
       def for(layout, obj)
@@ -41,21 +41,21 @@ module HaveAPI
         self::Output.new(*args)
       end
 
-      # Override this method to load validators from +model+
-      # to +params+.
+      # Override this method to load validators from `model`
+      # to `params`.
       def load_validators(model, params)
 
       end
 
       # Called when mounting the API. Model adapters may use this method
-      # to add custom meta parameters to +action+. +direction+ is one of
-      # +:input+ and +:output+.
+      # to add custom meta parameters to `action`. `direction` is one of
+      # `:input` and `:output`.
       def used_by(direction, action)
         case direction
-          when :input
-            self::Input.used_by(action)
-          when :output
-            self::Output.used_by(action)
+        when :input
+          self::Input.used_by(action)
+        when :output
+          self::Output.used_by(action)
         end
       end
     end
@@ -72,12 +72,12 @@ module HaveAPI
       end
 
       # Return true if input parameters contain parameter
-      # with +name+.
+      # with `name`.
       def has_param?(name)
         @input.has_key?(name)
       end
 
-      # Return parameter with +name+.
+      # Return parameter with `name`.
       def [](name)
         @input[name]
       end
@@ -101,7 +101,7 @@ module HaveAPI
       end
 
       # Return true if input parameters contain parameter
-      # with +name+.
+      # with `name`.
       def has_param?(name)
 
       end

data/lib/haveapi/model_adapters/active_record.rb

@@ -21,7 +21,7 @@ module HaveAPI::ModelAdapters
       module InstanceMethods
         # Helper method that sets correct ActiveRecord includes
         # according to the meta includes sent by the user.
-        # +q+ is the model or partial AR query. If not set,
+        # `q` is the model or partial AR query. If not set,
         # action's model class is used instead.
         def with_includes(q = nil)
           q ||= self.class.model
@@ -179,14 +179,14 @@ END
         end
 
         {
-            path_params: params.is_a?(Array) ? params : [params],
-            resolved: true
+          path_params: params.is_a?(Array) ? params : [params],
+          resolved: true
         }
       end
 
       protected
-      # Return representation of an associated resource +param+
-      # with its instance in +val+.
+      # Return representation of an associated resource `param`
+      # with its instance in `val`.
       #
       # By default, it returns an unresolved resource, which contains
       # only object id and label. Resource will be resolved
@@ -204,11 +204,11 @@ END
           pass_includes = includes_pass_on_to(param.name)
 
           show = res_show.new(
-              push_ins.request,
-              push_ins.version,
-              {},
-              nil,
-              @context
+            push_ins.request,
+            push_ins.version,
+            {},
+            nil,
+            @context
           )
           show.meta[:includes] = pass_includes
 
@@ -231,17 +231,17 @@ END
 
         else
           {
-              param.value_id => val.send(res_output[param.value_id].db_name),
-              param.value_label => val.send(res_output[param.value_label].db_name),
-              _meta: {
-                :path_params => args.is_a?(Array) ? args : [args],
-                :resolved => false
-              }
+            param.value_id => val.send(res_output[param.value_id].db_name),
+            param.value_label => val.send(res_output[param.value_label].db_name),
+            _meta: {
+              :path_params => args.is_a?(Array) ? args : [args],
+              :resolved => false
+            }
           }
         end
       end
 
-      # Should an association with +name+ be resolved?
+      # Should an association with `name` be resolved?
       def includes_include?(name)
         includes = @context.action_instance.meta[:includes]
         return unless includes
@@ -324,7 +324,7 @@ END
 
       handle ::ActiveModel::Validations::ExclusionValidator do |v|
         opts = {
-            values: v.options[:in].map { |v| v }
+          values: v.options[:in].map { |v| v }
         }
         opts[:message] = v.options[:message] if v.options[:message]
 
@@ -333,7 +333,7 @@ END
 
       handle ::ActiveModel::Validations::FormatValidator do |v|
         opts = {
-            rx: v.options[:with]
+          rx: v.options[:with]
         }
         opts[:message] = v.options[:message] if v.options[:message]
 
@@ -342,7 +342,7 @@ END
 
       handle ::ActiveModel::Validations::InclusionValidator do |v|
         opts = {
-            values: v.options[:in].map { |v| v }
+          values: v.options[:in].map { |v| v }
         }
         opts[:message] = v.options[:message] if v.options[:message]
 

data/lib/haveapi/output_formatter.rb

@@ -49,10 +49,10 @@ module HaveAPI
       ret = {}
       ret[:version] = HaveAPI::PROTOCOL_VERSION if version
       ret.update({
-          status: status,
-          response: response,
-          message: message,
-          errors: errors
+        status: status,
+        response: response,
+        message: message,
+        errors: errors
       })
       ret
     end

data/lib/haveapi/output_formatters/base.rb

@@ -13,7 +13,7 @@ module HaveAPI::OutputFormatters
 
       def handle?(type)
         @types.detect do |t|
-           File.fnmatch(type, t)
+          File.fnmatch(type, t)
         end
       end
     end

data/lib/haveapi/parameters/resource.rb

@@ -43,35 +43,35 @@ module HaveAPI::Parameters
 
     def describe(context)
       val_path = context.path_for(
-          @resource::Show,
-          context.endpoint && context.action_prepare && context.layout == :object && context.call_path_params(context.action, context.action_prepare)
+        @resource::Show,
+        context.endpoint && context.action_prepare && context.layout == :object && context.call_path_params(context.action, context.action_prepare)
       )
       val_method = @resource::Index.http_method.to_s.upcase
 
       choices_path = context.path_for(
-          @choices,
-          context.endpoint && context.layout == :object && context.call_path_params(context.action, context.action_prepare)
+        @choices,
+        context.endpoint && context.layout == :object && context.call_path_params(context.action, context.action_prepare)
       )
       choices_method = @choices.http_method.to_s.upcase
 
       {
-          required: required?,
-          label: @label,
-          description: @desc,
-          type: 'Resource',
-          resource: @resource_path,
-          value_id: @value_id,
-          value_label: @value_label,
-          value: context.action_prepare && {
-              path: val_path,
-              method: val_method,
-              help: "#{val_path}?method=#{val_method}",
-          },
-          choices: {
-              path: choices_path,
-              method: choices_method,
-              help: "#{choices_path}?method=#{choices_method}"
-          }
+        required: required?,
+        label: @label,
+        description: @desc,
+        type: 'Resource',
+        resource: @resource_path,
+        value_id: @value_id,
+        value_label: @value_label,
+        value: context.action_prepare && {
+          path: val_path,
+          method: val_method,
+          help: "#{val_path}?method=#{val_method}",
+        },
+        choices: {
+          path: choices_path,
+          method: choices_method,
+          help: "#{choices_path}?method=#{choices_method}"
+        }
       }
     end
 
@@ -93,7 +93,7 @@ module HaveAPI::Parameters
 
     def clean(raw)
       ::HaveAPI::ModelAdapter.for(
-          show_action.input.layout, @resource.model
+        show_action.input.layout, @resource.model
       ).input_clean(@resource.model, raw, @extra)
     end
 

data/lib/haveapi/parameters/typed.rb

@@ -46,13 +46,13 @@ module HaveAPI::Parameters
 
     def describe(context)
       {
-          required: required?,
-          label: @label,
-          description: @desc,
-          type: @type ? @type.to_s : String.to_s,
-          validators: @validators ? @validators.describe : {},
-          default: @default,
-          protected: @protected || false,
+        required: required?,
+        label: @label,
+        description: @desc,
+        type: @type ? @type.to_s : String.to_s,
+        validators: @validators ? @validators.describe : {},
+        default: @default,
+        protected: @protected || false,
       }
     end
 

data/lib/haveapi/params.rb

@@ -178,12 +178,14 @@ module HaveAPI
 
       if @direction == :input
         ret[:parameters] = context.authorization.filter_input(
-                             @params,
-                             ModelAdapters::Hash.output(context, ret[:parameters]))
+          @params,
+          ModelAdapters::Hash.output(context, ret[:parameters])
+        )
       else
         ret[:parameters] = context.authorization.filter_output(
-                             @params,
-                             ModelAdapters::Hash.output(context, ret[:parameters]))
+          @params,
+          ModelAdapters::Hash.output(context, ret[:parameters])
+        )
       end
 
       ret
@@ -205,11 +207,11 @@ module HaveAPI
       end
 
       case layout
-        when :object, :hash
-          params[namespace] ||= {}
+      when :object, :hash
+        params[namespace] ||= {}
 
-        when :object_list, :hash_list
-          params[namespace] ||= []
+      when :object_list, :hash_list
+        params[namespace] ||= []
       end
     end
 
@@ -298,14 +300,14 @@ module HaveAPI
 
     def valid_layout?(params)
       case layout
-        when :object, :hash
-          params[namespace].is_a?(Hash)
+      when :object, :hash
+        params[namespace].is_a?(Hash)
 
-        when :object_list, :hash_list
-          params[namespace].is_a?(Array)
+      when :object_list, :hash_list
+        params[namespace].is_a?(Array)
 
-        else
-          false
+      else
+        false
       end
     end
 
@@ -313,16 +315,16 @@ module HaveAPI
       ns = namespace
 
       case layout
-        when :object, :hash
-          yield(ns ? params[namespace] : params)
+      when :object, :hash
+        yield(ns ? params[namespace] : params)
 
-        when :object_list, :hash_list
-          (ns ? params[namespace] : params).each do |object|
-            yield(object)
-          end
+      when :object_list, :hash_list
+        (ns ? params[namespace] : params).each do |object|
+          yield(object)
+        end
 
-        else
-          false
+      else
+        false
       end
     end
 

data/lib/haveapi/resource.rb

@@ -59,20 +59,21 @@ module HaveAPI
       singular ? resource_name.singularize.underscore : resource_name.tableize
     end
 
-    def self.routes(prefix='/')
+    def self.routes(prefix='/', resource_path: [])
       ret = []
       prefix = "#{prefix}#{@route || rest_name}/"
+      new_resource_path = resource_path + [resource_name.underscore]
 
       actions do |a|
         # Call used_by for selected model adapters. It is safe to do
         # only when all classes are loaded.
         a.initialize
 
-        ret << Route.new(a.build_route(prefix).chomp('/'), a)
+        ret << Route.new(a.build_route(prefix).chomp('/'), a, new_resource_path)
       end
 
       resources do |r|
-        ret << {r => r.routes(prefix)}
+        ret << {r => r.routes(prefix, resource_path: new_resource_path)}
       end
 
       ret
@@ -83,6 +84,9 @@ module HaveAPI
 
       context.resource = self
 
+      orig_resource_path = context.resource_path
+      context.resource_path = context.resource_path + [resource_name.underscore]
+
       hash[:actions].each do |action, path|
         context.action = action
         context.path = path
@@ -97,6 +101,8 @@ module HaveAPI
         ret[:resources][resource.resource_name.underscore] = resource.describe(children, context)
       end
 
+      context.resource_path = orig_resource_path
+
       ret
     end