my_api_client 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f79acd9dda7576ad4ef44c65c31d5c6fd4c3ebe64dc6ce8106bd81097931b84
-  data.tar.gz: ff17d603eabd348ff39e7c209e3fa601bcbaeee1a97beeda73e46b9c6d16eda4
+  metadata.gz: d3ada9d2c8dbfadb9462b2cff381e9ccaf822a543f63672f6e5fdcd99f9ce4ed
+  data.tar.gz: b00cc646de8c05bc5378645940732e7dec5fc80d0dd4380e816f0a228e8b6f00
 SHA512:
-  metadata.gz: e3258a69b3e289f8277d307759aeca39ea14dd8f0573ef686cb5fb24625b7afe30d9be4e65fe896c7ca9ebdd25612c2fe07b980e72bcb8dfe63598c0297fe46d
-  data.tar.gz: 6cf8c1ee680e128f4ecfda474a528dc61323dba9ca592b7f044e5a9024a27eb6e8926cb4423909c7299198abca88d48aa127cb11d0b0f72d74e2e95c7310550d
+  metadata.gz: 977d55b39c0a35d56d4ff2ddc142765a7807f2b027471186d947cda8ea4f606d81fbfc842524318c9630f48a88aeb5adea5cc7e948233323f3072200e624d034
+  data.tar.gz: e8d4f395990d049afddc3e380044e5f65ad57d0130da1b08114d4bf28965a0d53fe756d147ebf17c7ffac3b236fc8c3f9e7fc7c74edfb90e9f57b0ed94b10930

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2019-05-27 23:30:42 +0000 using RuboCop version 0.70.0.
+# on 2019-05-30 23:31:07 +0000 using RuboCop version 0.71.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    my_api_client (0.3.0)
+    my_api_client (0.4.0)
       activesupport (>= 4.2.0)
       jsonpath
       sawyer
@@ -69,7 +69,7 @@ GEM
     rspec-support (3.8.0)
     rspec_junit_formatter (0.4.1)
       rspec-core (>= 2, < 4, != 2.12.0)
-    rubocop (0.70.0)
+    rubocop (0.71.0)
       jaro_winkler (~> 1.5.1)
       parallel (~> 1.10)
       parser (>= 2.6)

data/README.jp.md

@@ -2,7 +2,9 @@
 
 # MyApiClient
 
-MyApiClient は API リクエストクラスを作成するための汎用的な機能を提供します。Sawyer や Faraday をベースにエラーハンドリングの機能を強化した構造になっています。ただし、 Sawyer はダミーデータの作成が難しかったり、他の gem で競合することがよくあるので、将来的には依存しないように変更していくかもしれません。
+MyApiClient は API リクエストクラスを作成するための汎用的な機能を提供します。Sawyer や Faraday をベースにエラーハンドリングの機能を強化した構造になっています。
+
+ただし、 Sawyer はダミーデータの作成が難しかったり、他の gem で競合することがよくあるので、将来的には依存しないように変更していくかもしれません。
 
 また、 Ruby on Rails で利用することを想定してますが、それ以外の環境でも動作するように作っているつもりです。不具合などあれば Issue ページからご報告下さい。
 
@@ -13,7 +15,7 @@ MyApiClient は API リクエストクラスを作成するための汎用的な
 
 ## Installation
 
-この gem は macOS と Linux で作動します。まずは、my_api_client を Gemfile に追加します:
+この gem は macOS と Linux で作動します。まずは `my_api_client` を Gemfile に追加します:
 
 ```ruby
 gem 'my_api_client'
@@ -38,7 +40,7 @@ create    spec/api_clients/path/to/resource_api_client_spec.rb
 
 ```ruby
 class ExampleApiClient < MyApiClient::Base
-  endpoint 'https://example.com'
+  endpoint 'https://example.com/v1'
 
   attr_reader :access_token
 
@@ -46,14 +48,14 @@ class ExampleApiClient < MyApiClient::Base
     @access_token = access_token
   end
 
-  # GET https://example.com/users
+  # GET https://example.com/v1/users
   #
   # @return [Sawyer::Response] HTTP response parameter
   def get_users
     get 'users', headers: headers, query: { key: 'value' }
   end
 
-  # POST https://example.com/users
+  # POST https://example.com/v1/users
   #
   # @param name [String] Username which want to create
   # @return [Sawyer::Response] HTTP response parameter
@@ -75,8 +77,10 @@ api_clinet = ExampleApiClient.new(access_token: 'access_token')
 api_clinet.get_users #=> #<Sawyer::Response>
 ```
 
-クラス定義の最初に記述される `endpoint` にはリクエスト対象のスキーマとホストを定義します。ここにパス名を含めても反映されませんのでご注意ください。
+クラス定義の最初に記述される `endpoint` にはリクエスト URL の共通部分を定義します。後述の各メソッドで後続の path を定義しますが、上記の例だと `get 'users'` と定義すると、 `GET https://example.com/v1/users` というリクエストが実行されます。
+
 次に、 `#initialize` を定義します。上記の例のように Access Token や API Key などを設定することを想定します。必要なければ定義の省略も可能です。
+
 続いて、 `#get_users` や `#post_user` を定義します。メソッド名には API のタイトルを付けると良いと思います。メソッド内部で `#get` や `#post` を呼び出していますが、これがリクエスト時の HTTP Method になります。他にも `#patch` `#put` `#delete` が利用可能です。
 
 ### Error handling
@@ -121,7 +125,7 @@ error_handling status_code: 400..499, raise: MyApiClient::ClientError
 
 https://github.com/ryz310/my_api_client/blob/master/lib/my_api_client/errors.rb
 
-次に、 `raise` の代わりに Block を指定する場合について。
+次に、 `raise` の代わりに `block` を指定する場合について。
 
 ```ruby
 error_handling status_code: 500..599 do |params, logger|
@@ -130,7 +134,7 @@ error_handling status_code: 500..599 do |params, logger|
 end
 ```
 
-上記の例であれば、ステータスコードが `500..599` の場合に Block の内容が実行れます。引数の `params` にはリクエスト情報とレスポンス情報が含まれています。`logger` はログ出力用インスタンスですが、このインスタンスを使ってログ出力すると、以下のようにリクエスト情報がログ出力に含まれるようになり、デバッグの際に便利です。
+上記の例であれば、ステータスコードが `500..599` の場合に `block` の内容が実行れます。引数の `params` にはリクエスト情報とレスポンス情報が含まれています。`logger` はログ出力用インスタンスですが、このインスタンスを使ってログ出力すると、以下のようにリクエスト情報がログ出力に含まれるようになり、デバッグの際に便利です。
 
 ```text
 API request `GET https://example.com/path/to/resouce`: "Server error occurred."
@@ -155,7 +159,7 @@ error_handling json: { '$.errors.code': 10..19 }, with: :my_error_handling
 }
 ```
 
-`with` にはインスタンスメソッド名を指定することで、エラーを検出した際に任意のメソッドを実行させることができます。メソッドに渡される引数は Block 定義の場合と同じく `params` と `logger` です。
+`with` にはインスタンスメソッド名を指定することで、エラーを検出した際に任意のメソッドを実行させることができます。メソッドに渡される引数は `block` 定義の場合と同じく `params` と `logger` です。
 
 ```ruby
 # @param params [MyApiClient::Params::Params] HTTP req and res params
@@ -166,15 +170,59 @@ def my_error_handling(params, logger)
 end
 ```
 
-### Retry
+#### MyApiClient::Params::Params
 
 WIP
 
+#### MyApiClient::Error
+
+WIP
+
+### Retry
+
+次に `MyApiClient` が提供するリトライ機能についてご紹介致します。
+
+```ruby
+class ExampleApiClient < MyApiClient::Base
+  endpoint 'https://example.com'
+
+  retry_on MyApiClient::NetworkError, wait: 0.1.seconds, attempts: 3
+  retry_on MyApiClient::ApiLimitError, wait: 30.seconds, attempts: 3
+
+  error_handling json: { '$.errors.code': 20 }, raise: MyApiClient::ApiLimitError
+end
+```
+
+API リクエストを何度も実行していると回線の不調などによりネットワークエラーが発生する事があります。長時間ネットワークが使えなくなるケースもありますが、瞬間的なエラーであるケースも多々あります。 `MyApiClient` ではネットワーク系の例外はまとめて `MyApiClient::NetworkError` として `raise` されます。この例外の詳細は後述しますが、 `retry_on` を利用する事で、 `ActiveJob` のように任意の例外処理を補足して、一定回数、一定の期間を空けて API リクエストをリトライさせる事ができます。
+
+ただし、 `ActiveJob` とは異なり同期処理でリトライするため、ネットワークの瞬断に備えたリトライ以外ではあまり使う機会はないのではないかと思います。上記の例のように API Limit に備えてリトライするケースもあるかと思いますが、こちらは `ActiveJob` で対応した方が良いと思います。
+
+ちなみに一応 `discard_on` も実装していますが、作者自身が有効な用途を見出せていないので、詳細は割愛します。良い利用方法があれば教えてください。
+
 #### MyApiClient::NetworkError
 
+前述の通りですが、 `MyApiClient` ではネットワーク系の例外はまとめて `MyApiClient::NetworkError` として `raise` されます。他の例外と同じく `MyApiClient::Error` を親クラスとしています。 `MyApiClient::NetworkError` として扱われる例外クラスの一覧は `MyApiClient::NETWORK_ERRORS` で参照できます。また、元となった例外は `#original_error` で参照できます。
+
+```ruby
+begin
+  api_client.request
+rescue MyApiClient::NetworkError => e
+  e.original_error # => #<Net::OpenTimeout>
+  e.params.response # => nil
+end
+```
+
+なお、通常の例外はリクエストの結果によって発生しますが、この例外はリクエスト中に発生するため、例外インスタンスにレスポンスパラメータは含まれません。
+
+### Timeout
+
 WIP
 
-### One request for one class
+### Logger
+
+WIP
+
+## One request for one class
 
 多くの場合、同一ホストの API は リクエストヘッダーやエラー情報が同じ構造になっているため、上記のように一つのクラス内に複数の API を定義する設計が理にかなっていますが、 API 毎に個別に定義したい場合は、以下のように 1 つのクラスに 1 の API という構造で設計することも可能です。
 
@@ -224,13 +272,7 @@ class PostUserApiClient < ExampleApiClient
 end
 ```
 
-### Timeout
-
-WIP
-
-### Logger
-
-WIP
+## Testing
 
 ### RSpec
 
@@ -262,7 +304,7 @@ response = ExampleApiClient.new.request(user_id: 1)
 response.id # => 12345
 ```
 
-リクスエストパラメータを使ったレスポンスを返すようにスタブ化したい場合は、 block を利用することで実現できます。
+リクスエストパラメータを使ったレスポンスを返すようにスタブ化したい場合は、 `block` を利用することで実現できます。
 
 ```ruby
 my_api_client_stub(ExampleApiClient, :request) do |params|

data/lib/my_api_client.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'openssl'
+require 'net/http'
 require 'logger'
 require 'jsonpath'
 require 'active_support'

data/lib/my_api_client/config.rb

@@ -16,5 +16,24 @@ module MyApiClient
         METHOD
       end
     end
+
+    # Extracts schema and hostname from endpoint
+    #
+    # @example Extracts schema and hostname from 'https://example.com/path/to/api'
+    #   schema_and_hostname # => 'https://example.com'
+    # @return [String] description_of_returned_object
+    def schema_and_hostname
+      uri = URI.parse(endpoint)
+      "#{uri.scheme}://#{uri.host}"
+    end
+
+    # Extracts pathname from endpoint
+    #
+    # @example Extracts pathname from 'https://example.com/path/to/api'
+    #   common_path # => 'path/to/api'
+    # @return [String] The pathanem
+    def common_path
+      URI.parse(endpoint).path
+    end
   end
 end

data/lib/my_api_client/request.rb

@@ -14,8 +14,9 @@ module MyApiClient
     # @return [Sawyer::Resource] description_of_returned_object
     # rubocop:disable Metrics/ParameterLists
     def _request(http_method, pathname, headers, query, body, logger)
-      request_params = Params::Request.new(http_method, pathname, headers, query, body)
-      request_logger = Logger.new(logger, faraday, http_method, pathname)
+      processed_path = [common_path, pathname].join('/').gsub('//', '/')
+      request_params = Params::Request.new(http_method, processed_path, headers, query, body)
+      request_logger = Logger.new(logger, faraday, http_method, processed_path)
       call(:_execute, request_params, request_logger)
     end
     # rubocop:enable Metrics/ParameterLists
@@ -26,7 +27,7 @@ module MyApiClient
     #
     # @return [Sawyer::Agent] description_of_returned_object
     def agent
-      @agent ||= Sawyer::Agent.new(endpoint, faraday: faraday)
+      @agent ||= Sawyer::Agent.new(schema_and_hostname, faraday: faraday)
     end
 
     # Description of #faraday

data/lib/my_api_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module MyApiClient
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: my_api_client
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - ryz310
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-05-29 00:00:00.000000000 Z
+date: 2019-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport