my_api_client 0.14.0 → 0.18.0

data/Gemfile

@@ -4,9 +4,6 @@ source 'https://rubygems.org'
 
 git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
 
-# Workaound for ruby 2.4. Because activesupport v6.0.0 requires ruby 2.5 over.
-gem 'activesupport', '< 6.0.0'
-
 group :integrations, optional: true do
   gem 'bugsnag', '>= 6.11.0'
 end

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    my_api_client (0.14.0)
-      activesupport (>= 4.2.0)
+    my_api_client (0.18.0)
+      activesupport (>= 5.0.0)
       faraday (>= 0.17.1)
       jsonpath
       sawyer (>= 0.8.2)
@@ -10,79 +10,84 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (5.2.4.1)
+    activesupport (6.0.3.4)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
+      zeitwerk (~> 2.2, >= 2.2.2)
     addressable (2.7.0)
       public_suffix (>= 2.0.2, < 5.0)
-    ast (2.4.0)
-    bugsnag (6.13.0)
+    ast (2.4.1)
+    bugsnag (6.18.0)
       concurrent-ruby (~> 1.0)
-    byebug (11.1.1)
-    coderay (1.1.2)
-    concurrent-ruby (1.1.6)
-    crack (0.4.3)
-      safe_yaml (~> 1.0.0)
-    diff-lcs (1.3)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.7)
+    crack (0.4.4)
+    diff-lcs (1.4.4)
     docile (1.3.2)
-    faraday (1.0.0)
+    faraday (1.1.0)
       multipart-post (>= 1.2, < 3)
+      ruby2_keywords
     hashdiff (1.0.1)
-    i18n (1.8.2)
+    i18n (1.8.5)
       concurrent-ruby (~> 1.0)
-    jaro_winkler (1.5.4)
-    json (2.3.0)
-    jsonpath (1.0.5)
+    json (2.3.1)
+    jsonpath (1.0.6)
       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.2)
+    multi_json (1.15.0)
     multipart-post (2.1.1)
-    parallel (1.19.1)
-    parser (2.7.0.4)
-      ast (~> 2.4.0)
-    pry (0.12.2)
-      coderay (~> 1.1.0)
-      method_source (~> 0.9.0)
-    pry-byebug (3.8.0)
+    parallel (1.20.1)
+    parser (2.7.2.0)
+      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.6)
     rainbow (3.0.0)
     rake (13.0.1)
+    regexp_parser (2.0.0)
     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.1)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.0)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.1)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.2)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.0)
     rspec_junit_formatter (0.4.1)
       rspec-core (>= 2, < 4, != 2.12.0)
-    rubocop (0.80.1)
-      jaro_winkler (~> 1.5.1)
+    rubocop (1.5.1)
       parallel (~> 1.10)
-      parser (>= 2.7.0.1)
+      parser (>= 2.7.1.5)
       rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.0)
       rexml
+      rubocop-ast (>= 1.2.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.38.1)
-      rubocop (>= 0.68.1)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (1.3.0)
+      parser (>= 2.7.1.5)
+    rubocop-performance (1.9.1)
+      rubocop (>= 0.90.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    rubocop-rspec (2.0.1)
+      rubocop (~> 1.0)
+      rubocop-ast (>= 1.1.0)
     ruby-progressbar (1.10.1)
-    safe_yaml (1.0.5)
+    ruby2_keywords (0.0.2)
     sawyer (0.8.2)
       addressable (>= 2.3.5)
       faraday (> 0.8, < 2.0)
@@ -92,21 +97,20 @@ GEM
       simplecov-html (~> 0.10.0)
     simplecov-html (0.10.2)
     thread_safe (0.3.6)
-    to_regexp (0.2.1)
-    tzinfo (1.2.6)
+    tzinfo (1.2.8)
       thread_safe (~> 0.1)
-    unicode-display_width (1.6.1)
-    webmock (3.8.3)
+    unicode-display_width (1.7.0)
+    webmock (3.10.0)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
-    yard (0.9.24)
+    yard (0.9.25)
+    zeitwerk (2.4.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  activesupport (< 6.0.0)
   bugsnag (>= 6.11.0)
   bundler (>= 2.0)
   my_api_client!
@@ -122,4 +126,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   2.1.2
+   2.1.4

data/README.jp.md

@@ -6,12 +6,14 @@ MyApiClient は API リクエストクラスを作成するための汎用的な
 
 ただし、 Sawyer はダミーデータの作成が難しかったり、他の gem で競合することがよくあるので、将来的には依存しないように変更していくかもしれません。
 
-また、 Ruby on Rails で利用することを想定してますが、それ以外の環境でも動作するように作っているつもりです。不具合などあれば Issue ページからご報告下さい。
+また、 Ruby on Rails で利用することを想定してますが、それ以外の環境でも動作するように作っています。不具合などあれば Issue ページからご報告下さい。
+
+[toc]
 
 ## Supported Versions
 
-* Ruby 2.4, 2.5, 2.6, 2.7
-* Rails 4.2, 5.0, 5.1, 5.2, 6.0
+* Ruby 2.5, 2.6, 2.7
+* Rails 5.0, 5.1, 5.2, 6.0
 
 ## Installation
 
@@ -24,7 +26,7 @@ gem 'my_api_client'
 Ruby on Rails を利用している場合は `generator` 機能を利用できます。
 
 ```sh
-$ rails g api_client path/to/resource get:path/to/resource
+$ rails g api_client path/to/resource get:path/to/resource --endpoint https://example.com
 
 create  app/api_clients/application_api_client.rb
 create  app/api_clients/path/to/resource_api_client.rb
@@ -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 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::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` も実装していますが、作者自身が有効な用途を見出せていないので、詳細は割愛します。良い利用方法があれば教えてください。
 
@@ -567,6 +642,66 @@ rescue MyApiClient::Error => e
 end
 ```
 
+## Deployment
+
+この gem のリリースには [gem_comet](https://github.com/ryz310/gem_comet) を利用しています。
+`gem_comet` の README.md にも使い方が載っていますが、備忘録のため、こちらにもリリースフローを記載しておきます。
+
+### Preparement
+
+以下のコマンドで `.envrc` を作成し、 `GITHUB_ACCESS_TOKEN` を設定します。
+
+```sh
+$ cp .envrc.skeleton .envrc
+```
+
+以下のコマンドで `gem_comet` をインストールします。
+
+```sh
+$ gem install gem_comet
+```
+
+### USAGE
+
+以下のコマンドで、最後のリリースから現在までに merge した PR の一覧を確認できます。
+
+```sh
+$ gem_comet changelog
+```
+
+以下のコマンドで gem のリリースを実行します。
+`{VERSION}` には新しく付与するバージョン番号を指定します。
+
+```sh
+$ gem_comet release {VERSION}
+```
+
+実行すると、 https://github.com/ryz310/my_api_client/pulls に以下のような PR が作成されます。
+
+* [Update v0\.16\.1](https://github.com/ryz310/my_api_client/pull/297)
+* [Release v0\.16\.1](https://github.com/ryz310/my_api_client/pull/298)
+
+まず、 `Update v{VERSION}`  という PR から merge に取り掛かります。
+
+PR のコメントにも TODO が記載されていますが、まず、バージョン番号が正しく採番されているかを確認します。
+
+See: [314a4c0](https://github.com/ryz310/my_api_client/pull/297/commits/314a4c06f66324ce77b640b1ee8db5c84ee038a2)
+
+次に `CHANGELOG.md` を編集して、 CHANGELOG を見やすく整理します。
+
+See: [33a2d17](https://github.com/ryz310/my_api_client/pull/297/commits/33a2d1703c773813c837e74ee3181906b2f2e502)
+
+これらが整ったら、 `Update v{VERSION}`  を merge します。
+
+これでリリース準備が整ったので、`Release v{VERSION}`  の merge に取り掛かります。
+
+この PR にこれからリリースする gem に対する変更が全て載っています。
+変更内容の最終確認をして、 CI も通ったことを確認したら `Release v{VERSION}`  を merge します。
+
+あとは Circle CI 側で gem のリリースが自動実行されるので、暫く待ちましょう。
+
+お疲れさまでした :tea:
+
 ## Contributing
 
 不具合の報告や Pull Request を歓迎しています。OSS という事で自分はなるべく頑張って英語を使うようにしていますが、日本語での報告でも大丈夫です :+1: