my_api_client 0.13.0 → 0.16.1

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    my_api_client (0.13.0)
+    my_api_client (0.16.1)
       activesupport (>= 4.2.0)
       faraday (>= 0.17.1)
       jsonpath
@@ -10,75 +10,80 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (5.2.4.1)
+    activesupport (5.2.4.3)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
     addressable (2.7.0)
       public_suffix (>= 2.0.2, < 5.0)
-    ast (2.4.0)
-    bugsnag (6.12.2)
+    ast (2.4.1)
+    bugsnag (6.16.0)
       concurrent-ruby (~> 1.0)
-    byebug (11.1.0)
-    coderay (1.1.2)
-    concurrent-ruby (1.1.5)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.7)
     crack (0.4.3)
       safe_yaml (~> 1.0.0)
-    diff-lcs (1.3)
+    diff-lcs (1.4.4)
     docile (1.3.2)
-    faraday (1.0.0)
+    faraday (1.0.1)
       multipart-post (>= 1.2, < 3)
-    hashdiff (1.0.0)
-    i18n (1.8.2)
+    hashdiff (1.0.1)
+    i18n (1.8.5)
       concurrent-ruby (~> 1.0)
-    jaro_winkler (1.5.4)
-    json (2.3.0)
+    json (2.3.1)
     jsonpath (1.0.5)
       multi_json
       to_regexp (~> 0.2.1)
-    method_source (0.9.2)
-    minitest (5.14.0)
-    multi_json (1.14.1)
+    method_source (1.0.0)
+    minitest (5.14.1)
+    multi_json (1.15.0)
     multipart-post (2.1.1)
-    parallel (1.19.1)
-    parser (2.7.0.2)
-      ast (~> 2.4.0)
-    pry (0.12.2)
-      coderay (~> 1.1.0)
-      method_source (~> 0.9.0)
-    pry-byebug (3.7.0)
+    parallel (1.19.2)
+    parser (2.7.1.4)
+      ast (~> 2.4.1)
+    pry (0.13.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.9.0)
       byebug (~> 11.0)
-      pry (~> 0.10)
-    public_suffix (4.0.3)
+      pry (~> 0.13.0)
+    public_suffix (4.0.5)
     rainbow (3.0.0)
     rake (13.0.1)
+    regexp_parser (1.7.1)
+    rexml (3.2.4)
     rspec (3.9.0)
       rspec-core (~> 3.9.0)
       rspec-expectations (~> 3.9.0)
       rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.1)
-      rspec-support (~> 3.9.1)
-    rspec-expectations (3.9.0)
+    rspec-core (3.9.2)
+      rspec-support (~> 3.9.3)
+    rspec-expectations (3.9.2)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.9.0)
     rspec-mocks (3.9.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.9.0)
-    rspec-support (3.9.2)
+    rspec-support (3.9.3)
     rspec_junit_formatter (0.4.1)
       rspec-core (>= 2, < 4, != 2.12.0)
-    rubocop (0.79.0)
-      jaro_winkler (~> 1.5.1)
+    rubocop (0.89.1)
       parallel (~> 1.10)
-      parser (>= 2.7.0.1)
+      parser (>= 2.7.1.1)
       rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.7)
+      rexml
+      rubocop-ast (>= 0.3.0, < 1.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 1.7)
-    rubocop-performance (1.5.2)
-      rubocop (>= 0.71.0)
-    rubocop-rspec (1.37.1)
-      rubocop (>= 0.68.1)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (0.3.0)
+      parser (>= 2.7.1.4)
+    rubocop-performance (1.7.1)
+      rubocop (>= 0.82.0)
+    rubocop-rspec (1.43.2)
+      rubocop (~> 0.87)
     ruby-progressbar (1.10.1)
     safe_yaml (1.0.5)
     sawyer (0.8.2)
@@ -91,14 +96,14 @@ GEM
     simplecov-html (0.10.2)
     thread_safe (0.3.6)
     to_regexp (0.2.1)
-    tzinfo (1.2.6)
+    tzinfo (1.2.7)
       thread_safe (~> 0.1)
-    unicode-display_width (1.6.1)
-    webmock (3.8.0)
+    unicode-display_width (1.7.0)
+    webmock (3.8.3)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    yard (0.9.24)
+    yard (0.9.25)
 
 PLATFORMS
   ruby
@@ -115,9 +120,9 @@ DEPENDENCIES
   rubocop
   rubocop-performance
   rubocop-rspec
-  simplecov
+  simplecov (= 0.17.1)
   webmock
   yard
 
 BUNDLED WITH
-   2.1.2
+   2.1.4

data/README.jp.md

@@ -6,7 +6,9 @@ MyApiClient は API リクエストクラスを作成するための汎用的な
 
 ただし、 Sawyer はダミーデータの作成が難しかったり、他の gem で競合することがよくあるので、将来的には依存しないように変更していくかもしれません。
 
-また、 Ruby on Rails で利用することを想定してますが、それ以外の環境でも動作するように作っているつもりです。不具合などあれば Issue ページからご報告下さい。
+また、 Ruby on Rails で利用することを想定してますが、それ以外の環境でも動作するように作っています。不具合などあれば Issue ページからご報告下さい。
+
+[toc]
 
 ## Supported Versions
 
@@ -83,32 +85,95 @@ api_clinet.get_users #=> #<Sawyer::Response>
 
 続いて、 `#get_users` や `#post_user` を定義します。メソッド名には API のタイトルを付けると良いと思います。メソッド内部で `#get` や `#post` を呼び出していますが、これがリクエスト時の HTTP Method になります。他にも `#patch` `#put` `#delete` が利用可能です。
 
+### Pagination
+
+API の中にはレスポンスに結果の続きを取得するための URL を含んでいるものがあります。
+
+MyApiClient では、このような API を enumerable に扱うための `#pageable_get` というメソッドを用意しています。以下に例を示します。
+
+```ruby
+class MyPaginationApiClient < ApplicationApiClient
+  endpoint 'https://example.com/v1'
+
+  # GET pagination?page=1
+  def pagination
+    pageable_get 'pagination', paging: '$.links.next', headers: headers, query: { page: 1 }
+  end
+
+  private
+
+  def headers
+    { 'Content-Type': 'application/json;charset=UTF-8' }
+  end
+end
+```
+
+上記の例の場合、最初に `GET https://example.com/v1/pagination?page=1` に対してリクエストが実行され、続けてレスポンス JSON の `$.link.next` に含まれる URL に対して enumerable にリクエストを実行します。
+
+例えば以下のようなレスポンスであれば、`$.link.next` は `"https://example.com/pagination?page=3"` を示します。
+
+```json
+{
+  "links": {
+    "next": "https://example.com/pagination?page=3",
+    "previous": "https://example.com/pagination?page=1",
+  },
+  "page": 2
+}
+```
+
+そして `#pageable_get` は [Enumerator::Lazy](https://docs.ruby-lang.org/ja/latest/class/Enumerator=3a=3aLazy.html) を返すので、 `#each` や `#next` を実行することで次の結果を取得できます。
+
+```ruby
+api_clinet = MyPaginationApiClient.new
+api_clinet.pagination.each do |response|
+  # Do something.
+end
+
+p = api_clinet.pagination
+p.next # => 1st page result
+p.next # => 2nd page result
+p.next # => 3rd page result
+```
+
+なお、`#each` はレスポンスに含まれる `paging` の値が nil になるまで繰り返されるのでご注意ください。例えば `#take` と組み合わせることでページネーションの上限を設定できます。
+
+`#pageable_get` の alias として `#pget` も利用可能です。
+
+```ruby
+# GET pagination?page=1
+def pagination
+  pget 'pagination', paging: '$.links.next', headers: headers, query: { page: 1 }
+end
+```
+
 ### Error handling
 
-上記のコードにエラーハンドリングを追加してみます。
+`my_api_client` ではレスポンスの内容によって例外を発生させるエラーハンドリングを定義できます。ここでは例として前述のコードにエラーハンドリングを定義しています。
 
 ```ruby
 class ExampleApiClient < MyApiClient::Base
   endpoint 'https://example.com'
 
-  error_handling status_code: 400..499, raise: MyApiClient::ClientError
+  error_handling status_code: 400..499,
+                 raise: MyApiClient::ClientError
 
-  error_handling status_code: 500..599 do |params, logger|
+  error_handling status_code: 500..599, raise: MyApiClient::ServerError do |_params, logger|
     logger.warn 'Server error occurred.'
-    raise MyApiClient::ServerError, params
   end
 
-  error_handling json: { '$.errors.code': 10..19 }, with: :my_error_handling
+  error_handling json: { '$.errors.code': 10..19 },
+                 raise: MyApiClient::ClientError,
+                 with: :my_error_handling
 
   # Omission...
 
   private
 
-  # @param params [MyApiClient::Params::Params] HTTP req and res params
-  # @param logger [MyApiClient::Logger] Logger for a request processing
+  # @param params [MyApiClient::Params::Params] HTTP reqest and response params
+  # @param logger [MyApiClient::Request::Logger] Logger for a request processing
   def my_error_handling(params, logger)
     logger.warn "Response Body: #{params.response.body.inspect}"
-    raise MyApiClient::ClientError, params
   end
 end
 ```
@@ -121,29 +186,26 @@ error_handling status_code: 400..499, raise: MyApiClient::ClientError
 
 これは `ExampleApiClient` からのリクエスト全てにおいて、レスポンスのステータスコードが `400..499` であった場合に `MyApiClient::ClientError` が例外として発生するようになります。 `ExampleApiClient` を継承したクラスにもエラーハンドリングは適用されます。ステータスコードのエラーハンドリングは親クラスで定義すると良いと思います。
 
-なお、 `status_code` には `Integer` `Range` `Regexp` が指定可能です。`raise` には `MyApiClient::Error` を継承したクラスが指定可能です。`my_api_client` で標準で定義しているエラークラスについては以下のソースコードをご確認下さい。
+なお、 `status_code` には `Integer` `Range` `Regexp` が指定可能です。
+
+`raise` には `MyApiClient::Error` を継承したクラスが指定可能です。`my_api_client` で標準で定義しているエラークラスについては以下のソースコードをご確認下さい。 `raise` を省略した場合は `MyApiClient::Error` を発生するようになります。
 
-https://github.com/ryz310/my_api_client/blob/master/lib/my_api_client/errors.rb
+https://github.com/ryz310/my_api_client/blob/master/lib/my_api_client/errors
 
-次に、 `raise` の代わりに `block` を指定する場合について。
+次に、 `block` を指定する場合について。
 
 ```ruby
-error_handling status_code: 500..599 do |params, logger|
+error_handling status_code: 500..599, raise: MyApiClient::ServerError do |_params, logger|
   logger.warn 'Server error occurred.'
-  raise MyApiClient::ServerError, params
 end
 ```
 
-上記の例であれば、ステータスコードが `500..599` の場合に `block` の内容が実行れます。引数の `params` にはリクエスト情報とレスポンス情報が含まれています。`logger` はログ出力用インスタンスですが、このインスタンスを使ってログ出力すると、以下のようにリクエスト情報がログ出力に含まれるようになり、デバッグの際に便利です。
+上記の例であれば、ステータスコードが `500..599` の場合に `MyApiClient::ServerError`  を発生させる前に `block` の内容が実行れます。引数の `params` にはリクエスト情報とレスポンス情報が含まれています。`logger` はログ出力用インスタンスですが、このインスタンスを使ってログ出力すると、以下のようにリクエスト情報がログ出力に含まれるようになり、デバッグの際に便利です。
 
 ```text
 API request `GET https://example.com/path/to/resouce`: "Server error occurred."
 ```
 
-リクエストに失敗した場合は例外処理を実行する、という設計が一般的だと思われるので、基本的にブロックの最後に `raise` を実行する事になると思います。
-
-最後に `json` と `with` を利用する場合について。
-
 ```ruby
 error_handling json: { '$.errors.code': 10..19 }, with: :my_error_handling
 ```
@@ -159,17 +221,28 @@ error_handling json: { '$.errors.code': 10..19 }, with: :my_error_handling
 }
 ```
 
-`with` にはインスタンスメソッド名を指定することで、エラーを検出した際に任意のメソッドを実行させることができます。メソッドに渡される引数は `block` 定義の場合と同じく `params` と `logger` です。
+`with` にはインスタンスメソッド名を指定することで、エラーを検出した際、例外を発生させる前に任意のメソッドを実行させることができます。メソッドに渡される引数は `block` 定義の場合と同じく `params` と `logger` です。なお、 `block` と `with` は同時には利用できません。
 
 ```ruby
 # @param params [MyApiClient::Params::Params] HTTP req and res params
-# @param logger [MyApiClient::Logger] Logger for a request processing
+# @param logger [MyApiClient::Request::Logger] Logger for a request processing
 def my_error_handling(params, logger)
   logger.warn "Response Body: #{params.response.body.inspect}"
-  raise MyApiClient::ClientError, params
 end
 ```
 
+#### Default error handling
+
+`my_api_client` では、標準でステータスコード 400 ~ 500 番台のレスポンスを例外として処理するようにしています。ステータスコードが 400 番台場合は `MyApiClient::ClientError`、 500 番台の場合は `MyApiClient::ServerError` を継承した例外クラスが raise されます。
+
+また、 `MyApiClient::NetworkError` に対しても標準で `retry_on` が定義されています。
+
+いずれも override 可能ですので、必要に応じて `error_handling` を定義して下さい。
+
+以下のファイルで定義しています。
+
+https://github.com/ryz310/my_api_client/blob/master/lib/my_api_client/default_error_handlers.rb
+
 #### Symbol を利用する
 
 ```ruby
@@ -238,7 +311,9 @@ end
 
 API リクエストを何度も実行していると回線の不調などによりネットワークエラーが発生する事があります。長時間ネットワークが使えなくなるケースもありますが、瞬間的なエラーであるケースも多々あります。 `MyApiClient` ではネットワーク系の例外はまとめて `MyApiClient::NetworkError` として `raise` されます。この例外の詳細は後述しますが、 `retry_on` を利用する事で、 `ActiveJob` のように任意の例外処理を補足して、一定回数、一定の期間を空けて API リクエストをリトライさせる事ができます。
 
-ただし、 `ActiveJob` とは異なり同期処理でリトライするため、ネットワークの瞬断に備えたリトライ以外ではあまり使う機会はないのではないかと思います。上記の例のように API Limit に備えてリトライするケースもあるかと思いますが、こちらは `ActiveJob` で対応した方が良いと思います。
+なお、 `retry_on MyApiClient::NetworkError` は標準実装されているため、特別に定義せずとも自動的に適用されます。 `wait` や `attempts` に任意の値を設定したい場合のみ定義してご利用ください。
+
+ただし、 `ActiveJob` とは異なり同期処理でリトライするため、ネットワークの瞬断に備えたリトライ以外ではあまり使う機会はないのではないかと思います。上記の例のように API Rate Limit に備えてリトライするケースもあるかと思いますが、こちらは `ActiveJob` で対応した方が良いかもしれません。
 
 ちなみに一応 `discard_on` も実装していますが、作者自身が有効な用途を見出せていないので、詳細は割愛します。良い利用方法があれば教えてください。
 

data/bin/console

@@ -3,6 +3,10 @@
 
 require 'bundler/setup'
 require 'my_api_client'
+require './example/api_clients/my_error_api_client'
+require './example/api_clients/my_rest_api_client'
+require './example/api_clients/my_pagination_api_client'
+require './example/api_clients/my_status_api_client'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.

data/example/api_clients/application_api_client.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative 'my_errors'
+
+# An usage example of the `my_api_client`.
+class ApplicationApiClient < MyApiClient::Base
+  endpoint ENV['MY_API_ENDPOINT']
+
+  self.logger = ::Logger.new(nil)
+
+  http_open_timeout 5.seconds
+  http_read_timeout 5.seconds
+end

data/example/api_clients/my_error_api_client.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'application_api_client'
+
+# An usage example of the `my_api_client`.
+# See also: my_api/app/controllers/status_controller.rb
+class MyErrorApiClient < ApplicationApiClient
+  error_handling json: { '$.error.message': /You requested error code/ },
+                 raise: MyErrors::ErrorCodeOther
+
+  error_handling json: { '$.error.code': :zero? },
+                 raise: MyErrors::ErrorCode00
+
+  error_handling json: { '$.error.code': 10 },
+                 raise: MyErrors::ErrorCode10
+
+  error_handling json: { '$.error.code': 20..29 },
+                 raise: MyErrors::ErrorCode2x
+
+  error_handling json: { '$.error.code': 30 },
+                 status_code: 400,
+                 raise: MyErrors::ErrorCode30
+
+  # GET error/:code
+  def get_error(code:)
+    get "error/#{code}", headers: headers
+  end
+
+  private
+
+  def headers
+    { 'Content-Type': 'application/json;charset=UTF-8' }
+  end
+end

data/example/api_clients/my_errors.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module MyErrors
+  # 400 Bad Request
+  class BadRequest < MyApiClient::ClientError; end
+
+  # 401 Unauthorized
+  class Unauthorized < MyApiClient::ClientError; end
+
+  # 403 Forbidden
+  class Forbidden < MyApiClient::ClientError; end
+
+  # Error code: 0
+  class ErrorCode00 < MyApiClient::ClientError; end
+
+  # Error code: 10
+  class ErrorCode10 < MyApiClient::ClientError; end
+
+  # Error code: 20 to 29
+  class ErrorCode2x < MyApiClient::ClientError; end
+
+  # Error code: 30
+  class ErrorCode30 < MyApiClient::ClientError; end
+
+  # Error code: other
+  class ErrorCodeOther < MyApiClient::ClientError; end
+end

data/example/api_clients/my_pagination_api_client.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'application_api_client'
+
+# An usage example of the `my_api_client`.
+# See also: my_api/app/controllers/pagination_controller.rb
+class MyPaginationApiClient < ApplicationApiClient
+  # GET pagination?page=1
+  def pagination
+    pget 'pagination', paging: '$.links.next', headers: headers, query: { page: 1 }
+  end
+
+  private
+
+  def headers
+    { 'Content-Type': 'application/json;charset=UTF-8' }
+  end
+end