Skip to content

Scrivener pagination with headers and web linking

License

MIT, MIT licenses found

Licenses found

MIT
LICENSE
MIT
LICENSE.md
Notifications You must be signed in to change notification settings

beam-community/scrivener_headers

Repository files navigation

Scrivener.Headers

Continuous Integration Module Version Hex Docs Total Download License Last Updated

Helpers for paginating API responses with Scrivener and HTTP headers. Implements RFC-5988, the proposed standard for Web linking.

Setup

Add :scrivener_headers to mix.exs:

defp deps do
  [
    # ...
    {:scrivener_headers, "~> 3.2"}
    # ...
  ]
end

Usage

With Scrivener.Headers.paginate/2 we can easily set our pagination headers:

def index(conn, params) do
  page = MyApp.Person
         |> where([p], p.age > 30)
         |> order_by([p], desc: p.age)
         |> preload(:friends)
         |> MyApp.Repo.paginate(params)

  conn
  |> Scrivener.Headers.paginate(page)
  |> render("index.json", people: page.entries)
end

With curl --include we can see our new headers:

$ curl --include 'https://localhost:4000/people?page=5'
HTTP/1.1 200 OK
Link: <http://localhost:4000/people?page=1>; rel="first",
  <http://localhost:4000/people?page=30>; rel="last",
  <http://localhost:4000/people?page=6>; rel="next",
  <http://localhost:4000/people?page=4>; rel="prev"
Total: 300
Per-Page: 10

Using Custom Header Names

Override any number of pagination header names by passing opts with a :header_keys keyword list like so:

Screenever.Headers.paginate(page,
  header_keys: [
    total: "total",
    link: "link",
    per_page: "per-page",
    total_pages: "total-pages",
    page_number: "page-number"
  ]
)

Contributing

Contributions of all types are welcomed and encouraged. Please make appropriate use of Issues and Pull Requests. All code should have test coverage.

Copyright and License

Copyright (c) 2016 Sean Callan

Released under the MIT License.