# Scrivener.Headers

[![Continuous Integration](](
[![Module Version](](
[![Hex Docs](](
[![Total Download](](
[![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"}
    # ...

## 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)

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

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:

  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][issues] and [Pull Requests][pulls].  All code
should have test coverage.


## Copyright and License

Copyright (c) 2016 Sean Callan

Released under the [MIT License](./