rest_api_builder 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7044c0a51394cd9997b23d7c1189e32a3342cdc63c5b2d15faff2050857d8114
-  data.tar.gz: 77684c0bc571a4b424f9e5624bbc25eafd45246b954c0ad1b7f2a2ba20535649
+  metadata.gz: d192a166c3b73c990be9893ac5f08bfd601aed7c4cc9c8bd8419ce2fe20c32be
+  data.tar.gz: 9d9974f0d2451412333dec8979a8bcdd3268b7bba8d15f58d7ef9ce4ccb63f31
 SHA512:
-  metadata.gz: e4efb71298656b1703b9b147dfdb9901cb94ab70bc74c013224439270211d9ad92357d7886d0355491eea22bf9b368e33db1a111096da1e643a6dd7807c067c1
-  data.tar.gz: 5562e548abb6dc0c8798e6fbe238d07110f41a9bcf8953c31286178dc26d3b6170f22fef14140241e1a47ae43d4482765f9b473db6aee1640432ae347ce38908
+  metadata.gz: 23676f348f1feb5cb3b6d66b452af4ced13358ceec0f91591279d0db73e48b02bb06e415252c2a08708afc12fc6916c2d679dcffef3b6f625b58e2194ef36077
+  data.tar.gz: ce0e28889a73b8cc2924cc855e3feef7da8dbbca0d78551ad5cfd5c23ade751ffd9e11b42af711d19826614993fa94fa31544c371221e617f94ad06ef3fe57d5

data/README.md

@@ -8,193 +8,339 @@ RestClient is great, but after building a few API clients with it you will almos
 - Handling and extracting details from non-200 responses
 - Creating testing interfaces for your API clients
 
-This library's tries to solve these and similar issues by providing a set of helper methods to improve on [rest-client](https://github.com/rest-client/rest-client) features and an optional [webmock](https://github.com/bblimke/webmock) testing interface for it.
+This library tries to solve these and similar issues by providing a set of self-contained helper methods to improve on [rest-client](https://github.com/rest-client/rest-client) features with an optional [WebMock](https://github.com/bblimke/webmock) testing interface.
 
 ## Installation
 ```
 gem install rest_api_builder
 ```
 
-## WebMock interface installation
-Simply require webmock interface before your test, for example in your `test_helper.rb`:
+## RestAPIBuilder::Request
+Main RestAPIBuilder module which includes various helper methods for parsing RestClient responses, catching errors and composing request details. `handle_*` and `compose_*` methods are intended to be used in conjunction, but you can use any of them in any combination without relying on the rest.
+
 ```rb
-  # test_helper.rb
-  require "webmock"
-  require "rest_api_builder/webmock_request_expectations"
+# Basic usage
+require 'rest_api_builder'
+include RestAPIBuilder::Request
+
+logger = Logger.new(STDOUT)
+response = handle_json_response(logger: logger) do
+  RestClient::Request.execute(
+    {
+      **compose_json_request_options(
+        base_url: 'https://api.github.com',
+        path: '/users/octocat/orgs',
+        method: :get
+      ),
+      log: logger
+    }
+  )
+end
 
-  WebMock.enable!
+response[:success] # => true
+response[:status]  # => 200
+response[:body]    # => []
+```
 
-  # my_spec.rb 
-  require 'test_helper'
+Included methods:
 
-  describe 'my test' do
-    it 'performs a request' do
-      RestAPIBuilder::WebMockRequestExpectations.expect_execute(...).to_return(body: "hi!")
-      result = RestClient::Request.execute(...)
+### `#handle_response(options, &block)`
+Executes given block, expecting to receive RestClient::Response as a result.\
+Returns plain ruby hash with following keys: `:success, :status, :body, :headers`\
+This will gracefully handle non-200 responses, but will throw on any error without defined response(e.g server timeout)
 
-      # some assertions
-    end
-  end
+```rb
+require 'rest_api_builder'
+include RestAPIBuilder::Request
+
+# normal response
+response = handle_response do
+  RestClient::Request.execute(method: :get, url: 'https://api.github.com/users/octocat/orgs')
+end
+
+response[:success] # => true
+response[:status]  # => 200
+response[:body]    # => '[]'
+response[:headers] # => {:accept_ranges=>"bytes", :access_control_allow_origin=>"*", ...}
+
+# non-200 response that would result in RestClient::RequestFailed exception otherwise
+response = handle_response do
+  RestClient::Request.execute(method: :get, url: 'https://api.github.com/users/octocat/foobar')
+end
+
+response[:success] # => false
+response[:status]  # => 404
+response[:body]    # => "{\"message\":\"Not Found\",..."}"
+```
+
+#### Accepted Options:
+| Name   | Description |
+|--------|-------------|
+| logger | Any object with `<<` method, e.g `Logger` instance. Will be used to log *response* details in the same way that [RestClient's `log` option](https://github.com/rest-client/rest-client#logging) logs the request details. Optional |
+
+### `#handle_json_response(options, &block)`
+Behaves just like `#handle_response`, but will also attempt to decode response `:body`, returning it as is if a parsing error occurs.
+
+```rb
+require 'rest_api_builder'
+include RestAPIBuilder::Request
+
+# decodes JSON response body
+response = handle_json_response do
+  RestClient::Request.execute(method: :get, url: 'https://api.github.com/users/octocat/orgs')
+end
+
+response[:success] # => true
+response[:status]  # => 200
+response[:body]    # => []
+
+# returns body as is if it cannot be decoded
+response = handle_json_response do
+  RestClient::Request.execute(method: :get, url: 'https://github.com/foo/bar/test')
+end
+
+response[:success] # => false
+response[:status]  # => 404
+response[:body]    # => "Not Found"
 ```
 
-`RestAPIBuilder::WebMockRequestExpectations` expects that you have WebMock installed as a dependency.
+### `handle_response_error(&block)`
+Low-level API.\
+You can use this method if you want to work with regular `RestClient::Response` objects directly(e.g when using `block_response` or `raw_response` options). This will handle non-200 exceptions but will not do anything else.\
+Returns plain ruby hash with `:success` and `:raw_response` keys.
 
-## Usage
 ```rb
-require "rest_api_builder"
+require 'rest_api_builder'
+include RestAPIBuilder::Request
 
-class MyRequest
-  include RestAPIBuilder
+# returns RestClient::Response as :raw_response
+response = handle_response_error do
+  RestClient::Request.execute(method: :get, url: 'https://api.github.com/users/octocat/orgs')
+end
 
-  def execute(options)
-    handle_response do
-      RestClient::Request.execute(compose_request_options(**options))
-    end
-  end
+response[:success]      # => true
+response[:raw_response] # => <RestClient::Response 200 "[]">
 
-  def json_execute(options)
-    handle_json_response do
-      RestClient::Request.execute(compose_json_request_options(**options))
-    end
-  end
+# handles non-200 responses
+response = handle_response_error do
+  RestClient::Request.execute(
+    method: :get,
+    url: 'https://api.github.com/users/octocat/foobar',
+    raw_response: true
+  )
 end
 
-my_request = MyRequest.new
-
-# Simple request:
-response = my_request.execute(base_url: "example.com", method: :get)
-response[:success] #=> true
-response[:status]  #=> 200
-response[:body]    #=> "<!doctype html>\n<html>..."
-response[:headers] #=> {:accept_ranges=>"bytes", ...}
-
-# Non-200 responses:
-response = my_request.execute(base_url: "example.com", path: "/foo", method: :get)
-response[:success] #=> false
-response[:status]  #=> 404
-response[:body]    #=> "<!doctype html>\n<html>..."
-
-# JSON requests:
-response = my_request.json_execute(base_url: "api.github.com", path: "/users/octocat/orgs", method: :get)
-response[:success] #=> true
-response[:body]    #=> []
+response[:success]      # => false
+response[:raw_response] # => <RestClient::RawResponse @code=404, @file=#<Tempfile...>>
 ```
 
-## WebMock Expectations
+### `#compose_request_options(options)`
+Provides a more consistent interface for `RestClient::Request#execute`.\
+This method returns a hash of options which you can then pass to `RestClient::Request#execute`.
+
+```rb
+require 'rest_api_builder'
+include RestAPIBuilder::Request
+
+# basic usage
+response = RestClient::Request.execute(
+  compose_request_options(
+    base_url: 'https://api.github.com',
+    path: '/users/octocat/orgs',
+    method: :get
+  )
+)
+
+response.request.url # => "https://api.github.com/users/octocat/orgs"
+response.body        # => '[]'
+
+# advanced options
+result = handle_response_error do
+  RestClient::Request.execute(
+    compose_request_options(
+      base_url: 'https://api.github.com',
+      path: '/users/octocat/orgs',
+      method: :post,
+      body: 'Hello',
+      headers: { content_type: 'foobar' },
+      query: { foo: 'bar' }
+    )
+  )
+end
+request = result[:raw_response].request
+
+request.url     # => "https://api.github.com/users/octocat/orgs?foo=bar"
+request.headers # => {:content_type=>"foobar"}
+request.payload # => <RestClient::Payload 'Hello'>
+```
+
+#### Accepted Options:
+| Name     | Description |
+|----------|-------------|
+| base_url | Base URL of the request. Required. |
+| method   | HTTP method of the request(e.g :get, :post, :patch). Required. |
+| path     | Path to be appended to `base_url`. Optional. |
+| body     | Request Body. Optional. |
+| headers  | Request Headers. Optional. |
+| query    | Query hash to be appended to the resulting url. Optional. |
+
+### `#compose_json_request_options(options)`
+Same as `compose_request_options` but will also convert provided `body`(if any) to JSON and append `Content-Type: 'application/json'` to `headers`
+
 ```rb
-require "rest_api_builder"
-require "webmock"
-require "rest_api_builder/webmock_request_expectations"
+require 'rest_api_builder'
+include RestAPIBuilder::Request
+
+# basic usage
+result = handle_response_error do
+  RestClient::Request.execute(
+    compose_json_request_options(
+      base_url: 'https://api.github.com',
+      path: '/users/octocat/orgs',
+      method: :post,
+      body: {a: 1}
+    )
+  )
+end
+request = result[:raw_response].request
 
-WebMock.disable_net_connect!
+request.headers # => {:content_type=>:json}
+request.payload # => <RestClient::Payload "{\"a\":1}">
+```
+
+## RestAPIBuilder::APIClient
 
-class MyRequest
-  include RestAPIBuilder
+### `#define_resource_shortcuts(resources, resources_scope:, init_with:)`
+Dynamically defines attribute readers for given resources
 
-  def execute(options)
-    handle_response do
-      RestClient::Request.execute(compose_request_options(**options))
+```rb
+require 'rest_api_builder'
+
+module ReadmeExamples
+  module Resources
+    class Octocat
+      def orgs
+        RestClient::Request.execute(method: :get, url: 'https://api.github.com/users/octocat/orgs')
+      end
     end
   end
 
-  def json_execute(options)
-    handle_json_response do
-      RestClient::Request.execute(compose_json_request_options(**options))
+  class APIClient
+    include RestAPIBuilder::APIClient
+
+    def initialize
+      define_resource_shortcuts(
+        [:octocat],
+        resources_scope: ReadmeExamples::Resources,
+        init_with: ->(resource_class) { resource_class.new }
+      )
     end
   end
 end
 
-my_request = MyRequest.new
 
-Expectations = RestAPIBuilder::WebMockRequestExpectations
+GITHUB_API = ReadmeExamples::APIClient.new
 
-# Simple expectation
-Expectations.expect_execute(base_url: "test.com", method: :get)
-response = my_request.execute(base_url: "test.com", method: :get)
+response = GITHUB_API.octocat.orgs
+response.body # => '[]'
+response.code # => 200
+```
 
-response[:success] #=> true
-response[:status]  #=> 200
-response[:body]    #=> ''
-response[:headers] #=> {}
+#### Accepted Arguments:
+| Name            | Description |
+|-----------------|-------------|
+| resources       | Array of resources to define shortcuts for |
+| resources_scope | Module or String(path to Module) within which resource classes are contained |
+| init_with       | Lambda which will be called for each resource class. The result will be returned from the defined shortcut. **Note:** `init_with` lambda is only called once so resource class must be able to function as a singleton. |
 
-# Specifying expectation details with WebMock::Request methods
-Expectations
-  .expect_execute(base_url: "test.com", method: :get)
-  .to_return(status: 404, body: "not found")
-response = my_request.execute(base_url: "test.com", method: :get)
+## RestAPIBuilder::WebMockRequestExpectations
+Optional wrapper around WebMock mocking interface with various improvements. This module must be required explicitly and expects [WebMock](https://github.com/bblimke/webmock) to be installed as a dependency in your project.
 
-response[:success] #=> false
-response[:status]  #=> 404
-response[:body]    #=> "not found"
+### `#expect_execute(options)`
+Defines a request expectation using WebMock's `stub_request`.
+```rb
+require 'rest_api_builder'
+require 'rest_api_builder/webmock_request_expectations'
+include RestAPIBuilder::Request
+include RestAPIBuilder::WebMockRequestExpectations
+
+# basic usage with regular webmock interface
+expect_execute(
+  base_url: 'https://api.github.com',
+  path: '/users/octocat/orgs',
+  method: :post
+).with(body: {foo: 'bar'}).to_return(body: '[hello]')
+
+response = RestClient::Request.execute(
+  compose_request_options(
+    base_url: 'https://api.github.com',
+    path: '/users/octocat/orgs',
+    method: :post,
+    body: {foo: 'bar'}
+  )
+)
+
+response.body # => '[hello]'
+
+# using expect_execute's request and response options
+expect_execute(
+  base_url: 'https://api.github.com',
+  path: '/users/octocat',
+  method: :post,
+  # matches request body and query hashes partially by default
+  request: { body: {foo: 'bar'}, query: {a: 1, b: 2} },
+  response: { body: 'hello' }
+)
 
-# Specifying expectation details with :request and :response options
-Expectations.expect_execute(
-  base_url: "test.com", 
-  method: :post, 
-  response: { body: 'hello' }, 
-  request: { body: { foo: "bar" } } # body will be matched partially using hash_including matcher
+response = RestClient::Request.execute(
+  compose_request_options(
+    base_url: 'https://api.github.com',
+    path: '/users/octocat',
+    method: :post,
+    body: { foo: 'bar', bar: 'baz' }, 
+    query: { a: 1, b: 2 }
+  )
 )
-response = my_request.json_execute(base_url: "test.com", method: :post, body: { foo: "bar", bar: "baz" })
-response[:success] #=> true
-response[:body]    #=> 'hello'
 
-my_request.json_execute(base_url: "test.com", method: :post, body: {bar: "baz"}) # => Raises WebMock::NetConnectNotAllowedError
+response.body # => 'hello'
+```
+
+#### Accepted Options:
+| Name     | Description |
+|----------|-------------|
+| base_url | Base URL of the request expectation. Required. |
+| path     | HTTP method of the request. Required. |
+| method   | Path to be appended to `base_url`. Regular expressions are also supported. Optional. |
+| request  | Hash of options which will be passed to WebMock's `with` method with following changes: `body` hash is converted to `hash_including` expectation and `query` hash values are transformed to strings and then it's converted into `hash_including` expectation. Optional  |
+| response | Hash of options which will be passed to WebMock's `to_return` method unchanged. Optional |
 
-# Using #expect_json_execute
-Expectations.expect_json_execute(
-  base_url: "test.com", 
-  method: :get, 
-  response: { body: {hi: 'hello'} }
+### `#expect_json_execute(options)`
+Same as `expect_execute` but will also call JSON encode on `response.body`(if one is provided).
+
+```rb
+require 'rest_api_builder'
+require 'rest_api_builder/webmock_request_expectations'
+include RestAPIBuilder::Request
+include RestAPIBuilder::WebMockRequestExpectations
+
+expect_json_execute(
+  base_url: 'https://api.github.com',
+  path: '/users/octocat/orgs',
+  method: :get,
+  response: { body: { foo: 'bar' } }
 )
-response = my_request.execute(base_url: "test.com", method: :get)
-response[:success] #=> true
-response[:body]    #=> "{\"hi\":\"hello\"}"
+
+response = RestClient::Request.execute(
+  compose_request_options(
+    base_url: 'https://api.github.com',
+    path: '/users/octocat/orgs',
+    method: :get
+  )
+)
+
+response.body # => "{\"foo\":\"bar\"}"
 ```
 
-## Request API
-### RestAPIBuilder#compose_request_options(options)
-Composes request options that can be passed to `RestClient::Request.execute`.
-#### Options:
-* **base_url**: Base URL of the request. Required.
-* **method**: HTTP method of the request(e.g :get, :post, :patch). Required.
-* **path**: Path to be appended to the :base_url. Optional.
-* **body**: Request Body. Optional.
-* **headers**: Request Headers. Optional.
-* **query**: Query hash to be appended to the resulting url. Optional.
-
-### RestAPIBuilder#compose_json_request_options(options)
-Accepts same options as `compose_request_options` but will also:
-- Add `Content-Type: 'application/json'` to request `headers`
-- Convert request `body` to JSON if it's present
-
-### RestAPIBuilder#handle_response(options, &block)
-Executes given block, expecting to receive `RestClient::Response` as a result.\
-Returns **plain ruby hash** with following keys: `:success`, `:status`, `:body`, `:headers`\
-This will also gracefully handle non-200 responses, but will throw on any error without defined response(e.g server timeout)
-
-#### Options:
-* **logger**: A `Logger` instance. If provided, will log response details as RestClient wont do this by default. Optional
-
-### RestAPIBuilder#handle_json_response(options, &block)
-Same as `#handle_response` but will also attempt to decode response `:body`, returning it as is if a parsing error occurrs
-
-### RestAPIBuilder#handle_response_error(options, &block)
-Low-level API, you can use this method if you want to work with the RestClient's responses directly without any conversions(e.g when using `block_response` or `raw_response` options of RestClient). This will handle errors in the same way as `#handle_response` does, but will not do anything else.\
-Returns ruby hash with `:success` and `:raw_response` keys.
-
-## WebMockRequestExpectations API
-### RestAPIBuilder::WebMockRequestExpectations.expect_execute(options)
-Defines a request expectation using WebMock's `stub_request`. Returns an instance of `WebMock::RequestStub` on which methods such as `with`, `to_return`, `to_timeout` can be called.
-
-#### Options:
-* **base_url**: Base URL of the request. Required.
-* **method**: HTTP method of the request(e.g :get, :post, :patch). Required.
-* **path**: Path to be appended to the :base_url. Optional.
-* **request**: request details which will be passed to `WebMock::RequestStub#with` if provided. If `query` or `body` keys are present and are hashes, they will be converted into WebMock's `hash_including` matcher. Optional
-* **response**: response details which will be passed to `WebMock::RequestStub#to_return` if provided. Optional
-
-### RestAPIBuilder::WebMockRequestExpectations.expect_json_execute(options)
-A convenience shortcut for `#json_execute` which will convert `request[:body]` to JSON if it's present
 
 ## License
-MIT
+MIT

data/lib/rest_api_builder.rb

@@ -1,7 +1,3 @@
 require 'forwardable'
 require 'rest_api_builder/request'
 require 'rest_api_builder/api_client'
-
-module RestAPIBuilder
-  include RestAPIBuilder::Request
-end

data/lib/rest_api_builder/webmock_request_expectations.rb

@@ -1,45 +1,10 @@
-require 'webmock'
-require 'rest_api_builder/helpers/url_helper'
+require 'forwardable'
+require 'rest_api_builder/webmock_request_expectations/expectations'
 
 module RestAPIBuilder
-  class WebMockRequestExpectationsSingleton
-    include WebMock::API
-    include RestAPIBuilder::Helpers::UrlHelper
+  module WebMockRequestExpectations
+    extend Forwardable
 
-    def expect_json_execute(response: nil, **options)
-      if response && response[:body]
-        response = response.merge(body: JSON.generate(response[:body]))
-      end
-
-      expect_execute(**options, response: response)
-    end
-
-    def expect_execute(base_url:, method:, path: nil, request: nil, response: nil)
-      url = path.is_a?(Regexp) ? /#{base_url}#{path}/ : full_url(base_url, path)
-      expectation = stub_request(method, url)
-
-      if !request.nil? && request.any?
-        add_request_expectations(expectation, request)
-      end
-
-      expectation.to_return(response) if response
-
-      expectation
-    end
-
-    def add_request_expectations(expectation, request)
-      if request[:body].is_a?(Hash)
-        request = request.merge(body: hash_including(request[:body]))
-      end
-
-      if request[:query].is_a?(Hash)
-        query = request[:query].transform_values(&:to_s)
-        request = request.merge(query: hash_including(query))
-      end
-
-      expectation.with(request)
-    end
+    def_delegators Expectations, :expect_json_execute, :expect_execute
   end
-
-  WebMockRequestExpectations = WebMockRequestExpectationsSingleton.new
 end

data/lib/rest_api_builder/webmock_request_expectations/expectations.rb

@@ -0,0 +1,47 @@
+require 'webmock'
+require 'rest_api_builder/helpers/url_helper'
+
+module RestAPIBuilder
+  module WebMockRequestExpectations
+    module Expectations
+      extend WebMock::API
+      extend RestAPIBuilder::Helpers::UrlHelper
+
+      module_function
+
+      def expect_json_execute(response: nil, **options)
+        if response && response[:body]
+          response = response.merge(body: JSON.generate(response[:body]))
+        end
+
+        expect_execute(**options, response: response)
+      end
+
+      def expect_execute(base_url:, method:, path: nil, request: nil, response: nil)
+        url = path.is_a?(Regexp) ? /#{base_url}#{path}/ : full_url(base_url, path)
+        expectation = stub_request(method, url)
+
+        if !request.nil? && request.any?
+          add_request_expectations(expectation, request)
+        end
+
+        expectation.to_return(response) if response
+
+        expectation
+      end
+
+      def add_request_expectations(expectation, request)
+        if request[:body].is_a?(Hash)
+          request = request.merge(body: hash_including(request[:body]))
+        end
+
+        if request[:query].is_a?(Hash)
+          query = request[:query].transform_values(&:to_s)
+          request = request.merge(query: hash_including(query))
+        end
+
+        expectation.with(request)
+      end
+    end
+  end
+end

data/rest_api_builder.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name        = 'rest_api_builder'
-  s.version     = '0.1.3'
+  s.version     = '0.2.0'
   s.summary     = "A simple wrapper for rest-client"
   s.description = "A simple wrapper for rest-client aiming to make creation and testing of API clients easier."
   s.authors     = ["Alexey D"]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rest_api_builder
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Alexey D
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-09-27 00:00:00.000000000 Z
+date: 2020-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rubocop
@@ -69,6 +69,7 @@ files:
 - lib/rest_api_builder/request/request_options.rb
 - lib/rest_api_builder/request/response_handler.rb
 - lib/rest_api_builder/webmock_request_expectations.rb
+- lib/rest_api_builder/webmock_request_expectations/expectations.rb
 - rest_api_builder.gemspec
 homepage: https://github.com/alexeyds/rest_api_builder
 licenses: