View Source Jiraffe.Pagination behaviour (Jiraffe v0.1.1)

Defines functions to handle pagination.

Reasoning

The Jira REST API uses pagination to improve performance.

Pagination is enforced for operations that could return a large collection of items. When you make a request to a paginated resource, the response wraps the returned array of values in a JSON object with paging metadata.

For example:

{
  "startAt" : 0,
  "maxResults" : 10,
  "total": 200,
  "isLast": false,
  "values": [
      { /* result 0 */ },
      { /* result 1 */ },
      { /* result 2 */ }
  ]
}
  • startAt is the index of the first item returned in the page.
  • maxResults is the maximum number of items that a page can return. Each operation can have a different limit for the number of items returned, and these limits may change without notice. To find the maximum number of items that an operation could return, set maxResults to a large number—for example, over 1000—and if the returned value of maxResults is less than the requested value, the returned value is the maximum.
  • total is the total number of items contained in all pages. This number may change as the client requests the subsequent pages, therefore the client should always assume that the requested page can be empty. Note that this property is not returned for all operations.
  • isLast indicates whether the page returned is the last one. Note that this property is not returned for all operations.

See Reference

Usage

Warning! It's ment for internal use only.

  • Use use Jiraffe.Pagination in your module.
  • Define a function that returns a page of results. The function should accept a Jiraffe.Client.t() and a Keyword.t() as arguments and return a {:ok, Jiraffe.Pagination.Page.t()} or {:error, Jiraffe.Error.t()}.
  • In your module, you'll get a function (all/2) that returns a list of all results and a function (stream/2) that returns a stream of pages.
  • You can customize the names of these functions by passing a list of options to use Jiraffe.Pagination:
    • naming: [[page_fn: :get_page, stream: :stream_name, all: :all_name]]
    • page_fn is the name of the function that returns a page of results.
    • stream is the name of the function that returns a stream of pages.
    • all is the name of the function that returns a list of all results.
  • You can define multiple resources in the same module by passing a list of options to use Jiraffe.Pagination:
    • naming: [ [page_fn: :get_users_page, stream: :stream_users, all: :all_users], [page_fn: :get_issues_page, stream: :stream_issuers, all: :all_issues] ]

Example:

  defmodule PaginatedResource do
    use Jiraffe.Pagination

    def page(_client, _params) do
      {:ok, %{
        start_at: 0,
        max_results: 1,
        total: 2,
        is_last: true,
        values: ["Page 1", "Page 2"]
      }}
    end
  end

  iex> PaginatedResource.all(Jiraffe.client("https://example.atlassian.net", "a-token"), [])
  {:ok, ["Page 1", "Page 2"]}

Summary

Callbacks

@callback page(
  Jiraffe.Client.t(),
  term()
) :: {:ok, Jiraffe.ResultsPage.t()} | {:error, Jiraffe.Error.t()}
@callback transform_values([term()]) :: [term()] | map()