diff --git a/.rubocop_gradual.lock b/.rubocop_gradual.lock index 9e178ebe..9e7f646c 100644 --- a/.rubocop_gradual.lock +++ b/.rubocop_gradual.lock @@ -34,7 +34,7 @@ [69, 15, 38, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 1480816240], [79, 13, 23, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 2314399065] ], - "spec/oauth2/client_spec.rb:292714281": [ + "spec/oauth2/client_spec.rb:2143306493": [ [6, 1, 29, "RSpec/SpecFilePathFormat: Spec path should end with `o_auth2/client*_spec.rb`.", 439549885], [175, 7, 492, "RSpec/NoExpectationExample: No expectation found in this example.", 1272021224], [194, 7, 592, "RSpec/NoExpectationExample: No expectation found in this example.", 3428877205], diff --git a/CHANGELOG.md b/CHANGELOG.md index 264910a0..88c942ea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - improved documentation by @pboling - Document Mutual TLS (mTLS) usage with example in README (connection_opts.ssl client_cert/client_key and auth_scheme: :tls_client_auth) +- Document usage of flat query params using Faraday::FlatParamsEncoder, with example URI, in README +- Spec: verify flat params are preserved with Faraday::FlatParamsEncoder (skips on Faraday without FlatParamsEncoder) - documentation notes in code comments and README highlighting OAuth 2.1 differences, with references, such as: - PKCE required for auth code, - exact redirect URI match, diff --git a/README.md b/README.md index 5ea07326..40ec87b4 100644 --- a/README.md +++ b/README.md @@ -991,6 +991,48 @@ client = OAuth2::Client.new( end ``` +##### Using flat query params (Faraday::FlatParamsEncoder) + +Some APIs expect repeated key parameters to be sent as flat params rather than arrays. Faraday provides FlatParamsEncoder for this purpose. You can configure the oauth2 client to use it when building requests. + +```ruby +require "faraday" + +client = OAuth2::Client.new( + id, + secret, + site: "https://api.example.com", + # Pass Faraday connection options to make FlatParamsEncoder the default + connection_opts: { + request: {params_encoder: Faraday::FlatParamsEncoder}, + }, +) do |faraday| + faraday.request(:url_encoded) + faraday.adapter(:net_http) +end + +access = client.client_credentials.get_token + +# Example of a GET with two flat filter params (not an array): +# Results in: ?filter=order.clientCreatedTime%3E1445006997000&filter=order.clientCreatedTime%3C1445611797000 +resp = access.get( + "/v1/orders", + params: { + # Provide the values as an array; FlatParamsEncoder expands them as repeated keys + filter: [ + "order.clientCreatedTime>1445006997000", + "order.clientCreatedTime<1445611797000", + ], + }, +) +``` + +If you instead need to build a raw Faraday connection yourself, the equivalent configuration is: + +```ruby +conn = Faraday.new("https://api.example.com", request: {params_encoder: Faraday::FlatParamsEncoder}) +``` + #### Redirection The library follows up to `max_redirects` (default 5). diff --git a/docs/OAuth2.html b/docs/OAuth2.html index 5ac242ac..c86bff71 100644 --- a/docs/OAuth2.html +++ b/docs/OAuth2.html @@ -415,7 +415,7 @@

diff --git a/docs/OAuth2/AccessToken.html b/docs/OAuth2/AccessToken.html index be573ceb..7212e270 100644 --- a/docs/OAuth2/AccessToken.html +++ b/docs/OAuth2/AccessToken.html @@ -3069,7 +3069,7 @@

diff --git a/docs/OAuth2/Authenticator.html b/docs/OAuth2/Authenticator.html index d1e8ac9b..1fb60f7a 100644 --- a/docs/OAuth2/Authenticator.html +++ b/docs/OAuth2/Authenticator.html @@ -883,7 +883,7 @@

diff --git a/docs/OAuth2/Client.html b/docs/OAuth2/Client.html index 083e6461..359ce495 100644 --- a/docs/OAuth2/Client.html +++ b/docs/OAuth2/Client.html @@ -2656,7 +2656,7 @@

diff --git a/docs/OAuth2/Error.html b/docs/OAuth2/Error.html index 2a1497a9..13889173 100644 --- a/docs/OAuth2/Error.html +++ b/docs/OAuth2/Error.html @@ -772,7 +772,7 @@

diff --git a/docs/OAuth2/FilteredAttributes.html b/docs/OAuth2/FilteredAttributes.html index 8eecda7f..29e84587 100644 --- a/docs/OAuth2/FilteredAttributes.html +++ b/docs/OAuth2/FilteredAttributes.html @@ -335,7 +335,7 @@

diff --git a/docs/OAuth2/FilteredAttributes/ClassMethods.html b/docs/OAuth2/FilteredAttributes/ClassMethods.html index 8f462b6b..48dfc2fb 100644 --- a/docs/OAuth2/FilteredAttributes/ClassMethods.html +++ b/docs/OAuth2/FilteredAttributes/ClassMethods.html @@ -280,7 +280,7 @@

diff --git a/docs/OAuth2/Response.html b/docs/OAuth2/Response.html index 59b51256..e2671de9 100644 --- a/docs/OAuth2/Response.html +++ b/docs/OAuth2/Response.html @@ -1619,7 +1619,7 @@

diff --git a/docs/OAuth2/Strategy.html b/docs/OAuth2/Strategy.html index a2cb9437..2a3c3b80 100644 --- a/docs/OAuth2/Strategy.html +++ b/docs/OAuth2/Strategy.html @@ -107,7 +107,7 @@

Defined Under Namespace

diff --git a/docs/OAuth2/Strategy/Assertion.html b/docs/OAuth2/Strategy/Assertion.html index 431c6130..3a28ccf1 100644 --- a/docs/OAuth2/Strategy/Assertion.html +++ b/docs/OAuth2/Strategy/Assertion.html @@ -481,7 +481,7 @@

diff --git a/docs/OAuth2/Strategy/AuthCode.html b/docs/OAuth2/Strategy/AuthCode.html index eb2b5df1..c600087b 100644 --- a/docs/OAuth2/Strategy/AuthCode.html +++ b/docs/OAuth2/Strategy/AuthCode.html @@ -483,7 +483,7 @@

diff --git a/docs/OAuth2/Strategy/Base.html b/docs/OAuth2/Strategy/Base.html index b4cccf51..309f3020 100644 --- a/docs/OAuth2/Strategy/Base.html +++ b/docs/OAuth2/Strategy/Base.html @@ -195,7 +195,7 @@

diff --git a/docs/OAuth2/Strategy/ClientCredentials.html b/docs/OAuth2/Strategy/ClientCredentials.html index ae1ee71f..80e3c054 100644 --- a/docs/OAuth2/Strategy/ClientCredentials.html +++ b/docs/OAuth2/Strategy/ClientCredentials.html @@ -343,7 +343,7 @@

diff --git a/docs/OAuth2/Strategy/Implicit.html b/docs/OAuth2/Strategy/Implicit.html index 89cda099..8c2b73e8 100644 --- a/docs/OAuth2/Strategy/Implicit.html +++ b/docs/OAuth2/Strategy/Implicit.html @@ -420,7 +420,7 @@

diff --git a/docs/OAuth2/Strategy/Password.html b/docs/OAuth2/Strategy/Password.html index 7f30be63..28d25a19 100644 --- a/docs/OAuth2/Strategy/Password.html +++ b/docs/OAuth2/Strategy/Password.html @@ -374,7 +374,7 @@

diff --git a/docs/OAuth2/Version.html b/docs/OAuth2/Version.html index b77c91f2..de21a700 100644 --- a/docs/OAuth2/Version.html +++ b/docs/OAuth2/Version.html @@ -111,7 +111,7 @@

diff --git a/docs/_index.html b/docs/_index.html index 847f17b2..8cc10983 100644 --- a/docs/_index.html +++ b/docs/_index.html @@ -366,7 +366,7 @@

Namespace Listing A-Z

diff --git a/docs/file.CHANGELOG.html b/docs/file.CHANGELOG.html index b28f4c4b..61e1d9ba 100644 --- a/docs/file.CHANGELOG.html +++ b/docs/file.CHANGELOG.html @@ -67,6 +67,9 @@

Added