Skip to content

v5.8.0
Compare
Choose a tag to compare
@elrayle elrayle released this 04 Feb 13:12
· 92 commits to main since this release
v5.8.0
a24aa0c

Steps to update

bundle update qa

No additional steps are required.

Notable changes

  • Faraday gem is temporarily pinned to < 2.0. Additional work is required to support v2.0.
  • New feature: Pagination (see details below)

New features

Pagination (optional)

NOTE: For backward compatibility, if new parameters are not passed in with the request, the pagination information is not returned as part of the result.

When used, pagination requests and results follow the JSON API standard.

References:

To request pagination

Request Parameter Default Possible Values Description
format :json | :jsonapi see rules below if :json, return values as [Array<Hash>]; if :jsonapi, return as [Hash] following JSON API standard
page_offset positive integer < total number of results 11 1
page_limit positive integer > 0 5 see rules below

Rules for default format:

  • :json - if none of the new parameters are included
  • :json - if a valid value for format (e.g. :json | :jsonapi) is not specified
  • :jsonapi - if either page_offset or page_limit is specified

Rules for default page_limit:

  • all results - if none of the new parameters are included
  • all results - if only new parameter format=:json is included
  • otherwise, 10

Results for :json

Example:

[
    { "id": "1", "label": "term 1" },
    { "id": "2", "label": "term 2" },
    ...
    { "id": "10", "label": "term 10" }
]

Results for :jsonapi

Example:

{
  "data": [
    { "id": "1", "label": "term 1" },
    { "id": "2", "label": "term 2" },
    ...
    { "id": "10", "label": "term 10" }
  ],
  "meta": {
    "page": {
      "page_offset": "1",
      "page_limit": "10",
      "actual_page_size": "10",
      "total_num_found": "28",
    }
  }
  "links": {
    "self_url": "http://example.com/qa/search/local/states?q=new&format=json-api&page_limit=10&page_offset=1",
    "first_url": "http://example.com/qa/search/local/states?q=new&format=json-api&page_limit=10&page_offset=1",
    "prev_url": nil,
    "next_url": "http://example.com/qa/search/local/states?q=new&format=json-api&page_limit=10&page_offset=11",
    "last_url": "http://example.com/qa/search/local/states?q=new&format=json-api&page_limit=10&page_offset=21"
  }
}

See more examples in the documentation of the #build_response method.

How page_offset is calculated for pagination links

expected page boundaries

Expected page boundaries are always calculated starting from page_offset=1
and the current page_limit. The page boundaries will include the page_offsets
that cover all results. For example, page_limit=10 with 36 results will have
page boundaries 1, 11, 21, 31.

self url
  • The self url always has the page_offset for the current page, which defaults
    to 1 if not passed in.
first page url
  • The first page url always has page_offset=1.
last page url
  • The last page url always has page_offset equal to the last of the expected page
    boundaries regardless of the passed in page_offset. For the example where
    page_limit=10 with 36 results, the last page will always have page_offset=31.
prev page url

  • Previous' page_offset is calculated from the passed in page_offset whether or
    not it is on an expected page boundary.

  • For prev, page_offset = passed in page_offset - page_limit || nil if calculated as < 1

    • when current page_offset (e.g. 1) is less than page_limit (e.g. 10), then page_offset
      for prev will be nil (e.g. 1 - 10 = -9 which is < 1)
    • when current page_offset is an expected page boundary (e.g. 21), then
      page_offset for prev will also be a page boundary (e.g. 21 - 10 = 11
      which is an expected page boundary)
    • when current page_offset is not on an expected page boundary (e.g. 13), then
      page_offset for prev will not be on an expected page boundary (e.g. 13 - 10 = 3
      which is not an expected page boundary)
next page url

  • Next's page_offset is calculated from the passed in page_offset whether or
    not it is on an expected page boundary.

  • For next, page_offset = passed in page_offset + page_limit || nil if calculated > total number of results found

    • when current page_offset (e.g. 31) is greater than total number of results (e.g. 36),
      then page_offset for next will be nil (e.g. 31 + 10 = 41 which is > 36)
    • when current page_offset is an expected page boundary (e.g. 21), then
      page_offset for next will also be a page boundary (e.g. 21 + 10 = 31
      which is an expected page boundary)
    • when current page_offset is not on an expected page boundary (e.g. 13), then
      page_offset for next will not be on an expected page boundary (e.g. 13 + 10 = 23
      which is not an expected page boundary)

Change Log

Full Changelog: v5.7.0...v5.8.0

Merged pull requests:

  • wrap initialization in reloader.to_prepare to avoid autoload deprecation warning in some cases #349 (jrochkind)
  • add pagination service for non-linked data authorities following jsonapi standard #348 (elrayle)
  • temporarily pin Faraday gem to < 2.0 #347 (elrayle)
Assets 2
Loading