jeckle 0.4.0.beta3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: daea79214eac076d0f45217ccad97e299f0b8ed4
-  data.tar.gz: 815eb79a5058729ef025476a438cff1a5fc358c4
+SHA256:
+  metadata.gz: 39ce2c6f4ee95e7aa03d9b3b40ab8de60422e947cf4cc7cd7709c669c1f71a68
+  data.tar.gz: 138d161339af0ef6b9da3ba0a3990376e1b1255dafb17a1ab385ddfc528a50c4
 SHA512:
-  metadata.gz: d7299c4462181501c834c7b33cfde8d06beca7ad21611c87a2b173070e2e9f864b3f01977045ee914cb54efe71c8c913e6fdce6021669c37735303144688ef17
-  data.tar.gz: 83388f41b76f585a801c13d7f4742237448f6982c44a5210abc5c0e3f37ba1a6172d74aa65dc1eefb82f0a7e3002337536c89961c309f0a0b78134efd31aff44
+  metadata.gz: 0fa2bbe9ad7f9119d4fe2aad99494e807c4e75897db327a2ad3ab717fab62dafbb1e777a1b3edc9e501adb1aebac5c44f9da310cd86dbfacb244783ccb9dc8ed
+  data.tar.gz: cd7eceaa6bca85d8147b546c405bf1f4b6545284c564b08ba0c1e34868f5cfdfb20417ddc9c3b07f65566874613c9ee7bb29ce2a870dad655a95b3a218619df4

data/README.md

@@ -1,8 +1,6 @@
 # Jeckle
 
-[![Build Status](https://travis-ci.org/tomas-stefano/jeckle.svg?branch=master)](https://travis-ci.org/tomas-stefano/jeckle)
-[![Code Climate](https://codeclimate.com/github/tomas-stefano/jeckle.png)](https://codeclimate.com/github/tomas-stefano/jeckle)
-[![Test Coverage](https://codeclimate.com/github/tomas-stefano/jeckle/coverage.png)](https://codeclimate.com/github/tomas-stefano/jeckle)
+[![CI](https://github.com/tomas-stefano/jeckle/actions/workflows/ci.yml/badge.svg)](https://github.com/tomas-stefano/jeckle/actions/workflows/ci.yml)
 
 Wrap APIs with easiness and flexibility.
 
@@ -20,53 +18,105 @@ Let third party APIs be Heckle for your app's Jeckle.
 
 Add this line to your application's Gemfile:
 
-    gem 'jeckle'
+```ruby
+gem 'jeckle'
+```
 
 And then execute:
 
-    $ bundle
+```sh
+$ bundle
+```
 
-### For Rails applications
+## Usage
 
-We recommend to create a initializer:
+### Configuring an API
 
-```ruby
-# config/initializers/jeckle.rb
+Let's say you'd like to connect your app to Dribbble.com - a community of designers sharing screenshots of their work, process, and projects.
+
+First, you would need to configure the API:
 
+```ruby
 Jeckle.configure do |config|
-  config.register :some_service do |api|
-    api.base_uri = 'http://api.someservice.com'
-    api.headers = {
-      'Accept' => 'application/json'
-    }
-    api.namespaces = { prefix: 'api', version: 'v1' }
-    api.logger = Rails.logger
-    api.read_timeout = 5
+  config.register :dribbble do |api|
+    api.base_uri = 'http://api.dribbble.com'
+    api.middlewares do
+      response :json
+    end
   end
 end
 ```
 
-And then put your API stuff scoped inside a `services` folder:
+### Mapping resources
 
-```ruby
-# app/services/some_service/models/my_resource.rb
+Following the previous example, Dribbble.com consists of pieces of web designers work called "Shots". Each shot has the attributes `id`, `name`, `url` and `image_url`. A Jeckle resource representing Dribbble's shots would be something like this:
 
-module SomeService
-  module Models
-    class MyResource
-      include Jeckle::Resource
+```ruby
+class Shot
+  include Jeckle::Resource
 
-      api :some_service
+  api :dribbble
 
-      attribute :id
-    end
-  end
+  attribute :id, Integer
+  attribute :name, String
+  attribute :url, String
+  attribute :image_url, String
 end
 ```
 
+### Fetching data
+
+The resource class allows us to search shots through HTTP requests to the API, based on the provided information. For example, we can find a specific shot by providing its id to the `find` method:
+
+```ruby
+# GET http://api.dribbble.com/shots/1600459
+shot = Shot.find 1600459
+```
+
+That will return a `Shot` instance, containing the shot info:
+
+```ruby
+shot.id
+=> 1600459
+
+shot.name
+=> "Daryl Heckle And Jeckle Oates"
+
+shot.image_url
+=> "https://d13yacurqjgara.cloudfront.net/users/85699/screenshots/1600459/daryl_heckle_and_jeckle_oates-dribble.jpg"
+```
+
+You can also look for many shots matching one or more attributes, by using the `search` method:
+
+```ruby
+# GET http://api.dribbble.com/shots?name=avengers
+shots = Shot.search name: 'avengers'
+```
+
+### Attribute Aliasing
+
+Sometimes you want to call the API's attributes something else, either because their names aren't very concise or because they're out of you app's convention. If that's the case, you can add an `as` option:
+
+```ruby
+attribute :thumbnailSize, String, as: :thumbnail_size
+```
+
+Both mapping will work:
+
+```ruby
+shot.thumbnailSize
+=> "50x50"
+
+shot.thumbnail_size
+=> "50x50"
+```
+
+We're all set! Now we can expand the mapping of our API, e.g to add ability to search Dribbble Designer directory by adding Designer class, or we can expand the original mapping of Shot class to include more attributes, such as tags or comments.
+
+## Examples
+
+You can see more examples here: [https://github.com/tomas-stefano/jeckle/tree/master/examples](https://github.com/tomas-stefano/jeckle/tree/master/examples)
+
 ## Roadmap
 
-- Faraday middleware abstraction
-- Per action API
-- Comprehensive restful actions
-- Testability
+Follow [GitHub's milestones](https://github.com/tomas-stefano/jeckle/milestones)

data/lib/jeckle/api.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Jeckle
   class API
     attr_accessor :logger
@@ -10,14 +12,14 @@ module Jeckle
         conn.params = params
         conn.response :logger, logger
 
-        conn.basic_auth basic_auth[:username], basic_auth[:password] if basic_auth
-        conn.instance_exec &@middlewares_block if @middlewares_block
+        conn.request :authorization, :basic, basic_auth[:username], basic_auth[:password] if basic_auth
+        conn.instance_exec(&@middlewares_block) if @middlewares_block
       end
     end
 
     def basic_auth=(credential_params)
-      [:username, :password].all? do |key|
-        credential_params.has_key? key
+      %i[username password].all? do |key|
+        credential_params.key? key
       end or raise Jeckle::NoUsernameOrPasswordError, credential_params
 
       @basic_auth = credential_params

data/lib/jeckle/attribute_aliasing.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Jeckle
+  module AttributeAliasing
+    def attribute(name, coercion, options = {})
+      if (custom_name = options.delete(:as))
+        super(custom_name, coercion, options)
+
+        alias_method name, custom_name
+        alias_method :"#{name}=", :"#{custom_name}="
+      else
+        super
+      end
+    end
+  end
+end

data/lib/jeckle/errors.rb

@@ -1,29 +1,31 @@
+# frozen_string_literal: true
+
 module Jeckle
   class ArgumentError < ::ArgumentError; end
 
   class NoSuchAPIError < ArgumentError
     def initialize(api)
-      message = %{The API name '#{api}' doesn't exist in Jeckle definitions.
+      message = %(The API name '#{api}' doesn't exist in Jeckle definitions.
 
         Heckle: - Hey chum, what we can do now?
         Jeckle: - Old chap, you need to put the right API name!
         Heckle: - Hey pal, tell me the APIs then!
         Jeckle: - Deal the trays, old thing: #{Jeckle::Setup.registered_apis.keys}.
-      }
+      )
 
-      super message
+      super(message)
     end
   end
 
   class NoUsernameOrPasswordError < ArgumentError
-    def initialize(credentials)
-      message = %{No such keys "username" and "password" on `basic_auth` definition"
+    def initialize(_credentials)
+      message = %(No such keys "username" and "password" on `basic_auth` definition"
 
         Heckle: - Hey chum, what we can do now?
         Jeckle: - Old chap, you need to define a username and a password for basic auth!
-      }
+      )
 
-      super message
+      super(message)
     end
   end
 end

data/lib/jeckle/http.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Jeckle
   module HTTP
     def self.included(base)
@@ -11,8 +13,6 @@ module Jeckle
         end
       end
 
-      # @public
-      #
       # The name of the resource that Jeckle uses to make the request
       #
       # @example
@@ -41,23 +41,6 @@ module Jeckle
         @resource_name ||= model_name.element.pluralize
       end
 
-      # @public
-      #
-      # Overwritten the resource name without write the resource name method.
-      #
-      # @example
-      #
-      #   module OtherApi
-      #     class Project
-      #       include Jeckle::Resource
-      #       resource 'projects.json'
-      #     end
-      #   end
-      #
-      def resource(jeckle_resource_name)
-        @resource_name = jeckle_resource_name
-      end
-
       # The API name that Jeckle uses to find all the api settings like domain, headers, etc.
       #
       # @example
@@ -75,14 +58,14 @@ module Jeckle
       #
       def api(registered_api_name)
         api_mapping[:default_api] = Jeckle::Setup.registered_apis.fetch(registered_api_name)
-      rescue KeyError => e
+      rescue KeyError
         raise Jeckle::NoSuchAPIError, registered_api_name
       end
 
       # @deprecated Please use {#api} instead
       #
       def default_api(registered_api_name)
-        warn "[DEPRECATION] `default_api` is deprecated.  Please use `api` instead."
+        warn '[DEPRECATION] `default_api` is deprecated. Please use `api` instead.'
         api(registered_api_name)
       end
 
@@ -91,14 +74,8 @@ module Jeckle
       end
 
       def run_request(endpoint, options = {})
-        request = Jeckle::Request.run api_mapping[:default_api], endpoint, options
-
-        if logger = api_mapping[:default_api].logger
-          logger.debug("#{self} Response: #{request.response.body}")
-        end
-
-        request
+        Jeckle::Request.run api_mapping[:default_api], endpoint, options
       end
     end
   end
-end
+end

data/lib/jeckle/model.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 module Jeckle
   module Model
     def self.included(base)
-      base.send :include, ActiveModel::Validations
-      base.send :include, Virtus.model
+      base.include ActiveModel::Validations
+      base.include Virtus.model
     end
   end
 end

data/lib/jeckle/request.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Jeckle
   class Request
     attr_reader :api, :body, :headers, :method, :params, :response, :endpoint
@@ -6,17 +8,28 @@ module Jeckle
       @api = api
 
       @method  = options.delete(:method) || :get
-      @body    = options.delete(:body) if %w(post put).include?(method.to_s)
+      @body    = options.delete(:body) if %w[post put patch].include?(method.to_s)
       @headers = options.delete(:headers)
 
+      if options[:params].nil? && options.size.positive?
+        warn %([DEPRECATION] Sending URL params mixed with options hash is deprecated.
+        Instead of doing this:
+          run_request 'cars/search', id: id, method: :get
+        Do this:
+          run_request 'cars/search', params: { id: id }, method: :get)
+
+        @params = options
+      else
+        @params = options.delete(:params) || {}
+      end
+
       @endpoint = endpoint
-      @params = options
 
       @response = perform_api_request
     end
 
-    def self.run(*args)
-      new *args
+    def self.run(api, endpoint, options = {})
+      new(api, endpoint, options)
     end
 
     private

data/lib/jeckle/resource.rb

@@ -1,11 +1,15 @@
+# frozen_string_literal: true
+
 module Jeckle
   module Resource
     def self.included(base)
-      base.send :include, ActiveModel::Naming
+      base.include ActiveModel::Naming
+
+      base.include Jeckle::Model
+      base.include Jeckle::HTTP
+      base.include Jeckle::RESTActions
 
-      base.send :include, Jeckle::Model
-      base.send :include, Jeckle::HTTP
-      base.send :include, Jeckle::RESTActions
+      base.extend Jeckle::AttributeAliasing
     end
   end
 end

data/lib/jeckle/rest_actions.rb

@@ -1,106 +1,27 @@
+# frozen_string_literal: true
+
 module Jeckle
   module RESTActions
     def self.included(base)
-      base.send :extend, Jeckle::RESTActions::Collection
+      base.extend Jeckle::RESTActions::Collection
     end
 
     module Collection
-      # @public
-      #
-      # The root name that Jeckle will parse the <b>response</b>. Default is <b>false</b>.
-      #
-      # @example
-      #
-      #   module Dribble
-      #     class Shot
-      #       include Jeckle::Resource
-      #       root collection: true, member: true
-      #     end
-      #   end
-      #
-      #   Shot.collection_root_name # => Will parse the root node as 'shots'
-      #   Shot.member_root_name # => Will parse the root node as 'shot'
-      #
-      #  Sometimes that are APIs you need to fetch /projects, BUT the root node is extremely different from the resource name.
-      #
-      #   module OtherApi
-      #     class Project
-      #       include Jeckle::Resource
-      #       api :my_api
-      #       root collection: 'awesome-projects', member: 'awesome-project'
-      #     end
-      #   end
-      #
-      def root(options={})
-        @collection_root_name = find_root_name(options[:collection], :pluralize)
-        @member_root_name     = find_root_name(options[:member], :singularize)
-      end
-
-      # @public
-      #
-      # Member action that requests for the resource using the resource name
-      #
-      #  @example
-      #
-      #     Post.find(1) # => posts/1
-      #
       def find(id)
-        endpoint   = "#{resource_name}/#{id}"
-        response   = run_request(endpoint).response.body
-        attributes = parse_response(response, member_root_name)
+        endpoint = "#{resource_name}/#{id}"
+        attributes = run_request(endpoint).response.body
 
-        new(attributes)
+        new attributes
       end
 
-      # @public
-      #
-      # Collection action that requests for the resource using the resource name
-      #
-      #  @example
-      #
-      #     Post.search({ status: 'published' }) # => posts/?status=published
-      #     Post.where({ status: 'published' }) # => posts/?status=published
-      #
       def search(params = {})
-        request    = run_request(resource_name, params)
-        response   = request.response
-        collection = parse_response(response.body, collection_root_name)
+        custom_resource_name = params.delete(:resource_name) if params.is_a?(Hash)
 
-        CollectionResponse.new(collection, context: self, response: response)
-      end
-      alias :where :search
-
-      # @private
-      #
-      def parse_response(response, root_name)
-        if root_name
-          response[root_name]
-        else
-          response
-        end
-      end
-
-      # @private
-      #
-      def find_root_name(root_name, root_method)
-        return root_name if root_name.is_a?(String)
-
-        if root_name
-          model_name.element.send(root_method)
-        end
-      end
-
-      # @private
-      #
-      def collection_root_name
-        @collection_root_name
-      end
+        response   = run_request(custom_resource_name || resource_name, params: params).response.body || []
+        collection = response.is_a?(Array) ? response : response[resource_name]
 
-      # @private
-      #
-      def member_root_name
-        @member_root_name
+        Array(collection).collect { |attrs| new attrs }
       end
     end
   end
-end
+end

data/lib/jeckle/setup.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 module Jeckle
   class Setup
-    # Register apis, providing all the configurations to it.
+    # Register APIs, providing all the configurations to it.
     #
     # @example
     #

data/lib/jeckle/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Jeckle
-  VERSION = '0.4.0.beta3'
+  VERSION = '0.4.0'
 end

data/lib/jeckle.rb

@@ -1,14 +1,12 @@
+# frozen_string_literal: true
+
 require 'active_model'
 require 'faraday'
-require 'faraday_middleware'
 require 'virtus'
 
 require 'jeckle/version'
 
-%w(
-    setup api model request http rest_actions
-    resource errors collection_response
-).each do |file_name|
+%w[setup api model request http rest_actions resource errors attribute_aliasing].each do |file_name|
   require "jeckle/#{file_name}"
 end