my_api_client 2.0.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/Gemfile.lock CHANGED
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- my_api_client (2.0.0)
4
+ my_api_client (2.2.0)
5
5
  activesupport (>= 7.2.0)
6
6
  faraday (>= 0.17.1)
7
7
  jsonpath
@@ -10,7 +10,7 @@ PATH
10
10
  GEM
11
11
  remote: https://rubygems.org/
12
12
  specs:
13
- activesupport (8.1.3)
13
+ activesupport (8.1.4)
14
14
  base64
15
15
  bigdecimal
16
16
  concurrent-ruby (~> 1.0, >= 1.3.1)
@@ -27,7 +27,7 @@ GEM
27
27
  public_suffix (>= 2.0.2, < 8.0)
28
28
  ast (2.4.3)
29
29
  base64 (0.3.0)
30
- bigdecimal (4.1.2)
30
+ bigdecimal (4.1.3)
31
31
  bugsnag (6.30.0)
32
32
  concurrent-ruby (~> 1.0)
33
33
  byebug (13.0.0)
@@ -39,9 +39,8 @@ GEM
39
39
  bigdecimal
40
40
  rexml
41
41
  diff-lcs (1.6.2)
42
- docile (1.4.1)
43
42
  drb (2.2.3)
44
- faraday (2.14.3)
43
+ faraday (2.14.4)
45
44
  faraday-net_http (>= 2.0, < 3.5)
46
45
  json
47
46
  logger
@@ -51,7 +50,7 @@ GEM
51
50
  i18n (1.15.2)
52
51
  concurrent-ruby (~> 1.0)
53
52
  io-console (0.8.2)
54
- json (2.21.1)
53
+ json (2.21.2)
55
54
  jsonpath (1.1.5)
56
55
  multi_json
57
56
  language_server-protocol (3.17.0.6)
@@ -64,7 +63,7 @@ GEM
64
63
  multi_json (1.21.1)
65
64
  net-http (0.9.1)
66
65
  uri (>= 0.11.1)
67
- parallel (1.28.0)
66
+ parallel (2.3.0)
68
67
  parser (3.3.12.0)
69
68
  ast (~> 2.4.1)
70
69
  racc
@@ -80,7 +79,7 @@ GEM
80
79
  racc (1.8.1)
81
80
  rainbow (3.1.1)
82
81
  rake (13.4.2)
83
- regexp_parser (2.12.0)
82
+ regexp_parser (2.13.1)
84
83
  reline (0.6.3)
85
84
  io-console (~> 0.5)
86
85
  rexml (3.4.4)
@@ -99,7 +98,7 @@ GEM
99
98
  rspec-support (3.13.7)
100
99
  rspec_junit_formatter (0.6.0)
101
100
  rspec-core (>= 2, < 4, != 2.12.0)
102
- rubocop (1.88.2)
101
+ rubocop (1.89.0)
103
102
  json (~> 2.3)
104
103
  language_server-protocol (~> 3.17.0.2)
105
104
  lint_roller (~> 1.1.0)
@@ -113,9 +112,9 @@ GEM
113
112
  rubocop-ast (1.50.0)
114
113
  parser (>= 3.3.7.2)
115
114
  prism (~> 1.7)
116
- rubocop-performance (1.26.1)
115
+ rubocop-performance (1.27.0)
117
116
  lint_roller (~> 1.1)
118
- rubocop (>= 1.75.0, < 2.0)
117
+ rubocop (>= 1.89.0, < 2.0)
119
118
  rubocop-ast (>= 1.47.1, < 2.0)
120
119
  rubocop-rake (0.7.1)
121
120
  lint_roller (~> 1.1)
@@ -124,28 +123,23 @@ GEM
124
123
  lint_roller (~> 1.1)
125
124
  regexp_parser (>= 2.0)
126
125
  rubocop (~> 1.86, >= 1.86.2)
127
- rubocop-rspec_rails (2.32.0)
126
+ rubocop-rspec_rails (2.33.0)
128
127
  lint_roller (~> 1.1)
129
- rubocop (~> 1.72, >= 1.72.1)
128
+ rubocop (~> 1.89)
130
129
  rubocop-rspec (~> 3.5)
131
130
  ruby-progressbar (1.13.0)
132
131
  sawyer (0.9.3)
133
132
  addressable (>= 2.3.5)
134
133
  faraday (>= 0.17.3, < 3)
135
134
  securerandom (0.4.1)
136
- simplecov (0.22.0)
137
- docile (~> 1.1)
138
- simplecov-html (~> 0.11)
139
- simplecov_json_formatter (~> 0.1)
140
- simplecov-html (0.13.2)
141
- simplecov_json_formatter (0.1.4)
135
+ simplecov (1.3.2)
142
136
  tzinfo (2.0.6)
143
137
  concurrent-ruby (~> 1.0)
144
- unicode-display_width (3.2.0)
145
- unicode-emoji (~> 4.1)
146
- unicode-emoji (4.2.0)
147
- uri (1.1.1)
148
- webmock (3.26.2)
138
+ unicode-display_width (3.3.0)
139
+ unicode-emoji (~> 4.3)
140
+ unicode-emoji (4.3.0)
141
+ uri (1.1.2)
142
+ webmock (3.31.0)
149
143
  addressable (>= 2.8.0)
150
144
  crack (>= 0.3.2)
151
145
  hashdiff (>= 0.4.0, < 2.0.0)
@@ -167,7 +161,7 @@ DEPENDENCIES
167
161
  rubocop-rake
168
162
  rubocop-rspec
169
163
  rubocop-rspec_rails
170
- simplecov (= 0.22.0)
164
+ simplecov (= 1.3.2)
171
165
  webmock
172
166
  yard
173
167
 
data/README.md CHANGED
@@ -16,7 +16,7 @@ It is primarily designed for Ruby on Rails, but it also works in other environme
16
16
 
17
17
  ## Supported Versions
18
18
 
19
- - Ruby 3.2, 3.3, 3.4, 4.0
19
+ - Ruby 3.3, 3.4, 4.0
20
20
  - Rails 7.2, 8.0, 8.1
21
21
 
22
22
  ## Installation
@@ -87,8 +87,12 @@ api_client.get_users #=> #<Sawyer::Resource>
87
87
 
88
88
  Next, define `#initialize` to set values such as an access token or API key. You can omit it if you do not need any instance state.
89
89
 
90
+ `MyApiClient::Base` intentionally does not define `#initialize`, so a class that directly inherits from it does not need to call `super()` from its own `#initialize`. If you inherit from another application-specific client class, follow that parent class's initialization contract.
91
+
90
92
  Then define methods such as `#get_users` and `#post_user`. Inside those methods, call HTTP helpers like `#get` and `#post`. You can also use `#patch`, `#put`, and `#delete`.
91
93
 
94
+ Without a block, these HTTP helpers return the response body as a `Sawyer::Resource`. With a block, they yield the full `Sawyer::Response` and return the block's result. See [RSpec](#rspec) for the request and error-handling test helpers provided by this gem.
95
+
92
96
  ### Pagination
93
97
 
94
98
  Some APIs include a URL for the next page in the response.
@@ -260,6 +264,8 @@ Also, `retry_on` is defined by default for `MyApiClient::NetworkError`.
260
264
 
261
265
  Both can be overridden, so define `error_handling` as needed.
262
266
 
267
+ If more than one error handler matches a response, the handler defined last takes precedence. Handlers defined in a subclass are evaluated before inherited handlers, so a subclass can override a built-in handler with a more specific rule.
268
+
263
269
  They are defined [here](https://github.com/ryz310/my_api_client/blob/master/lib/my_api_client/default_error_handlers.rb).
264
270
 
265
271
  #### Use Symbol
@@ -343,6 +349,8 @@ end
343
349
 
344
350
  When an API request is executed many times, network errors can occur. Sometimes the network is unavailable for a long time, but often the error is temporary. In MyApiClient, network-related exceptions are wrapped as `MyApiClient::NetworkError`. Using `retry_on`, you can handle such exceptions and retry requests with configurable wait time and attempt count, similar to `ActiveJob`.
345
351
 
352
+ `attempts` is the number of retries after the initial request, not the total number of requests. For example, `attempts: 0` sends at most one request, while `attempts: 3` sends at most four requests.
353
+
346
354
  `retry_on MyApiClient::NetworkError` is enabled by default, so you do not need to define it unless you want custom `wait` or `attempts` values.
347
355
 
348
356
  Unlike `ActiveJob`, retries are performed synchronously. In practice, this is most useful for short-lived network interruptions. You can also retry for API rate limits as in the example above, but handling that with `ActiveJob` may be a better fit depending on your workload.
@@ -426,8 +434,7 @@ MyApiClient wraps this logger with `MyApiClient::Request::Logger` and prefixes m
426
434
 
427
435
  ```text
428
436
  API request `GET https://example.com/v1/users`: "Start"
429
- API request `GET https://example.com/v1/users`: "Duration 100.0 msec"
430
- API request `GET https://example.com/v1/users`: "Success (200)"
437
+ API request `GET https://example.com/v1/users`: "Success (200) in 100.0 msec"
431
438
  ```
432
439
 
433
440
  On failure, it logs:
@@ -662,7 +669,7 @@ stub_api_client_all(ExampleApiClient, request: { raise: MyApiClient::Error })
662
669
  expect { ExampleApiClient.new.request(user_id: 1) }.to raise_error(MyApiClient::Error)
663
670
  ```
664
671
 
665
- You can combine `raise`, `response`, and `status_code`:
672
+ You can combine `raise`, `response`, `status_code`, and `headers`:
666
673
 
667
674
  ```ruby
668
675
  stub_api_client_all(
@@ -671,17 +678,23 @@ stub_api_client_all(
671
678
  raise: MyApiClient::Error,
672
679
  response: { message: 'error' },
673
680
  status_code: 429,
681
+ headers: { 'Retry-After' => '60' },
674
682
  }
675
683
  )
676
684
 
677
685
  begin
678
686
  ExampleApiClient.new.request(user_id: 1)
679
687
  rescue MyApiClient::Error => e
680
- e.params.response.data.to_h # => { message: "error" }
681
- e.params.response.status # => 429
688
+ e.params.response.data.to_h # => { message: "error" }
689
+ e.params.response.status # => 429
690
+ e.params.response.headers['retry-after'] # => "60"
682
691
  end
683
692
  ```
684
693
 
694
+ Stubbed headers behave like real response headers: names are looked up case-insensitively and values are converted to Strings. Use String keys for header names, because Symbol keys are rewritten (e.g. `:retry_after` becomes `'Retry-After'`).
695
+
696
+ If the `raise` option is an error instance, `response`, `status_code`, and `headers` cannot be combined with it. Pass an error class instead.
697
+
685
698
  #### `pageable` option
686
699
 
687
700
  For `#pageable_get` (`#pget`), you can stub page-by-page responses:
@@ -24,6 +24,15 @@ sed -n '1,260p' AGENTS.md
24
24
  ## Auto-merge workflow policy
25
25
  - Keep `package-ecosystem` decisions separated in `.github/workflows/dependabot-auto-merge.yml`.
26
26
  - Apply independent conditions for each ecosystem to avoid cross-ecosystem condition mixing.
27
+ - For `bundler` ecosystem auto-merge:
28
+ - Verification apps (`rails_app/*` and `my_api`) are always auto-merged regardless of update type
29
+ (including major), because bundle update failures there do not affect the published gem and are
30
+ gated by CI/branch protection.
31
+ - Exception: a major update of the `rails` gem itself under `rails_app/*` is NOT auto-merged,
32
+ because a Rails major bump is treated as an explicit support-matrix decision that requires manual
33
+ review. Other gems' major updates under `rails_app/*` are still auto-merged.
34
+ - The gem itself (root `Gemfile`) is auto-merged only for `direct:development` dependencies on
35
+ non-major updates (patch/minor).
27
36
  - For `github-actions` ecosystem auto-merge, require all of the following:
28
37
  - GitHub official actions only (`actions/*` or `github/*`)
29
38
  - non-major updates only (patch/minor)
@@ -32,13 +32,13 @@ module MyApiClient
32
32
  def call
33
33
  request_logger.info('Start')
34
34
  response = api_request
35
- request_logger.info("Duration #{response.timing.in_milliseconds} msec")
35
+ duration = " in #{response.timing.in_milliseconds} msec"
36
36
  verify(response)
37
37
  rescue MyApiClient::Error => e
38
- request_logger.warn("Failure (#{e.message})")
38
+ request_logger.warn("Failure (#{e.message})#{duration}")
39
39
  raise
40
40
  else
41
- request_logger.info("Success (#{response.status})")
41
+ request_logger.info("Success (#{response.status})#{duration}")
42
42
  response
43
43
  end
44
44
 
@@ -4,9 +4,9 @@ module MyApiClient
4
4
  # Test helper module for RSpec
5
5
  module Stub
6
6
  ERROR_MESSAGE =
7
- 'If you use the `raise` option as an error instance, the `response` option ' \
8
- 'is ignored. If you want to use both options, you need to specify the ' \
9
- '`raise` option as an error class.'
7
+ 'If you use the `raise` option as an error instance, the `response`, ' \
8
+ '`status_code` and `headers` options are ignored. If you want to use them, ' \
9
+ 'you need to specify the `raise` option as an error class.'
10
10
 
11
11
  # Stubs all instance of arbitrary MyApiClient class.
12
12
  # And returns a stubbed arbitrary MyApiClient instance.
@@ -22,13 +22,14 @@ module MyApiClient
22
22
  # pageable: [ { id: 1 }, { id: 2 }] # for `#pageable_get`.
23
23
  # },
24
24
  # get_user: { response: { id: 1 } }, # Returns an arbitrary response.
25
- # post_users: { id: 1 }, # You can ommit `response` keyword.
25
+ # post_users: { id: 1 }, # You can omit `response` keyword.
26
26
  # patch_user: ->(params) { { id: params[:id] } }, # Returns calculated result as response.
27
27
  # put_user: { raise: MyApiClient::ClientError } # Raises an arbitrary error.
28
28
  # delete_user: {
29
29
  # raise: MyApiClient::ClientError,
30
- # response: { errors: [{ code: 10 }] }, # You can stub response and statu code
30
+ # response: { errors: [{ code: 10 }] }, # You can stub response and status code
31
31
  # status_code: 429, # with an arbitrary error.
32
+ # headers: { 'X-Request-Id' => '123' }, # You can also stub response headers.
32
33
  # }
33
34
  # )
34
35
  # response = ExampleApiClient.new.get_user(id: 123)
@@ -54,13 +55,14 @@ module MyApiClient
54
55
  # pageable: [ { id: 1 }, { id: 2 }] # for `#pageable_get`.
55
56
  # },
56
57
  # get_user: { response: { id: 1 } }, # Returns an arbitrary response.
57
- # post_users: { id: 1 }, # You can ommit `response` keyword.
58
+ # post_users: { id: 1 }, # You can omit `response` keyword.
58
59
  # patch_user: ->(params) { { id: params[:id] } }, # Returns calculated result as response.
59
60
  # put_user: { raise: MyApiClient::ClientError } # Raises an arbitrary error.
60
61
  # delete_user: {
61
62
  # raise: MyApiClient::ClientError,
62
63
  # response: { errors: [{ code: 10 }] }, # You can stub response and status code
63
64
  # status_code: 403, # with exception.
65
+ # headers: { 'X-Request-Id' => '123' }, # You can also stub response headers.
64
66
  # }
65
67
  # )
66
68
  # response = api_client.get_user(id: 123)
@@ -82,13 +84,13 @@ module MyApiClient
82
84
  end
83
85
  end
84
86
 
85
- def generate_stubbed_response(options, *request) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
87
+ def generate_stubbed_response(options, *request) # rubocop:disable Metrics/MethodLength
86
88
  case options
87
89
  when Proc
88
90
  stub_as_resource(options.call(*request))
89
91
  when Hash
90
92
  if options[:raise]
91
- raise process_raise_option(options[:raise], options[:response], options[:status_code])
93
+ raise process_raise_option(options)
92
94
  elsif options[:response]
93
95
  stub_as_resource(options[:response])
94
96
  elsif options[:pageable].is_a?(Enumerable)
@@ -113,37 +115,47 @@ module MyApiClient
113
115
 
114
116
  # Provides a shorthand for `raise` option.
115
117
  # `MyApiClient::Error` requires `MyApiClient::Params::Params` instance on
116
- # initialize, but it makes trubolesome. `MyApiClient::NetworkError` is more.
118
+ # initialize, but it makes troublesome. `MyApiClient::NetworkError` is more.
117
119
  # If given a error instance, it will return raw value without processing.
118
120
  #
119
- # @param exception [Clsas, MyApiClient::Error] Processing target.
120
- # @param response [Hash] describe_response_here
121
- # @param status_code [Integer] describe_status_code_here
121
+ # @param options [Hash] Stubbing options.
122
+ # @option options [Class, MyApiClient::Error] :raise Processing target.
123
+ # @option options [Hash] :response Stubbed response body.
124
+ # @option options [Integer] :status_code Stubbed status code (defaults to 400).
125
+ # @option options [Hash] :headers
126
+ # Stubbed response headers. Keys are looked up case-insensitively like real
127
+ # response headers and values are converted to Strings, so prefer String keys
128
+ # (e.g. `'X-Request-Id'`).
122
129
  # @return [MyApiClient::Error] Processed exception.
123
130
  # @raise [RuntimeError] Unsupported error class was set.
124
- def process_raise_option(exception, response, status_code)
125
- case exception
131
+ def process_raise_option(options)
132
+ case options[:raise]
126
133
  when Class
127
- params = MyApiClient::Params::Params.new(nil, stub_as_response(response, status_code))
128
- if exception == MyApiClient::NetworkError
129
- exception.new(params, Net::OpenTimeout.new)
130
- else
131
- exception.new(params)
132
- end
134
+ build_stubbed_error(*options.values_at(:raise, :response, :status_code, :headers))
133
135
  when MyApiClient::Error
134
- raise ERROR_MESSAGE if response.present?
136
+ raise ERROR_MESSAGE if options.values_at(:response, :status_code, :headers).any?(&:present?)
137
+
138
+ options[:raise]
139
+ else
140
+ raise "Unsupported error class was set: #{options[:raise].inspect}"
141
+ end
142
+ end
135
143
 
136
- exception
144
+ def build_stubbed_error(exception, response, status_code, headers)
145
+ stubbed_response = stub_as_response(response, status_code, headers)
146
+ params = MyApiClient::Params::Params.new(nil, stubbed_response)
147
+ if exception == MyApiClient::NetworkError
148
+ exception.new(params, Net::OpenTimeout.new)
137
149
  else
138
- raise "Unsupported error class was set: #{exception.inspect}"
150
+ exception.new(params)
139
151
  end
140
152
  end
141
153
 
142
- def stub_as_response(params, status_code)
154
+ def stub_as_response(params, status_code, headers = nil)
143
155
  instance_double(
144
156
  Sawyer::Response,
145
157
  status: status_code.presence || 400,
146
- headers: {},
158
+ headers: Faraday::Utils::Headers.new(headers),
147
159
  data: stub_as_resource(params),
148
160
  body: params.to_json,
149
161
  timing: 0.123
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module MyApiClient
4
- VERSION = '2.0.0'
4
+ VERSION = '2.2.0'
5
5
  end
data/my_api/Gemfile CHANGED
@@ -3,7 +3,7 @@
3
3
  source 'https://rubygems.org'
4
4
 
5
5
  gem 'puma', '>= 6.0'
6
- gem 'rails', '~> 8.1.3'
6
+ gem 'rails', '~> 8.1.4'
7
7
 
8
8
  group :development, :test do
9
9
  gem 'rspec-rails'