chore: add NestedParamPaginator to README and CHANGELOG

Author: Doug Smith

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- [#348](https://github.com/JsonApiClient/json_api_client/pull/348) - add NestedParamPaginator to address inconsistency in handling of pagination query string params (issue [#347](https://github.com/JsonApiClient/json_api_client/issues/347)).
+
 ## 1.12.0
 
 - [#345](https://github.com/JsonApiClient/json_api_client/pull/345) - track the real HTTP reason of ApiErrors

README.md

@@ -599,6 +599,20 @@ class MyApi::Base < JsonApiClient::Resource
 end
 ```
 
+### NestedParamPaginator
+
+The current default `JsonApiClient::Paginating::Paginator` is inconsistent in the way it handles pagination query string params. The JSON:API spec seems to favor a nested structure like `page[page]=1&page[per_page]=10`. However, the default paginator doesn't always return or enforce that nested structure. See issue [#347](https://github.com/JsonApiClient/json_api_client/issues/347) for more details.
+
+If you'd like a more consistent pagination query string param behavior, assign the `JsonApiClient::Paginating::NestedParamPaginator` to your resource as a custom paginator, like so:
+
+```ruby
+class Order < JsonApiClient::Resource
+  self.paginator = JsonApiClient::Paginating::NestedParamPaginator
+end
+```
+
+You can also extend `NestedParamPaginator` in your custom paginators or assign the `page_param` or `per_page_param` as with the default version above.
+
 ### Custom type
 
 If your model must be named differently from classified type of resource you can easily customize it.