Opinionated Pagination Helpers for Servant APIs

Client can provide a Range header with their request with the following format

Range: <field> [<value>][; offset <o>][; limit <l>][; order <asc|desc>]

Available ranges are declared using type-level list of accepted fields, bound to a given resource and type using the HasPagination type-class. The library provides unobtrusive types and abstract away all the plumbing to hook that on an existing Servant API.

The IsRangeType constraints summarize all constraints that must apply to a possible field and heavily rely on the FromHttpApiData and ToHttpApiData.

$ curl -v http://localhost:1337/colors -H 'Range: name; limit 10'

> GET /colors HTTP/1.1
> Host: localhost:1337
> User-Agent: curl/7.47.0
> Accept: */*
>
< HTTP/1.1 206 Partial Content
< Transfer-Encoding: chunked
< Date: Tue, 30 Jan 2018 12:45:17 GMT
< Server: Warp/3.2.13
< Content-Type: application/json;charset=utf-8
< Accept-Ranges: name
< Content-Range: name Yellow..Purple
< Next-Range: name Purple;limit 10;offset 1;order desc

The Range header is totally optional, but when provided, it indicates to the server what parts of the collection is requested. As a reponse and in addition to the data, the server may provide 3 headers to the client:

• Accept-Ranges: A comma-separated list of field upon which a range can be defined
• Content-Range: Actual range corresponding to the content being returned
• Next-Range: Indicate what should be the next Range header in order to retrieve the next range

This allows the client to work in a very _dumb_ mode where it simply consumes data from the server using the value of the 'Next-Range' header to fetch each new batch of data. The 'Accept-Ranges' comes in handy to self-document the API telling the client about the available filtering and sorting options of a resource.

Here's a minimal example used to obtained the previous behavior; Most of the magic happens in the returnRange function which lift a collection of resources into a Servant handler, computing the corresponding ranges from the range used to retrieve the resources.

-- Resource Type

data Color = Color
  { name :: String
  , rgb  :: [Int]
  , hex  :: String
  } deriving (Eq, Show, Generic)

colors :: [Color]
colors = [ {- ... -} ]

-- Ranges definitions

instance HasPagination Color "name" where
  type RangeType Color "name" = String
  getFieldValue _ = name


-- API

type API =
  "colors"
    :> Header "Range" (Ranges '["name"] Color)
    :> GetPartialContent '[JSON] (Headers (PageHeaders '["name"] Color) [Color])


-- Application

defaultRange :: Range "name" String
defaultRange =
  getDefaultRange (Proxy @Color)

server :: Server API
server mrange = do
  let range =
        fromMaybe defaultRange (mrange >>= extractRange)

  returnRange range (applyRange range colors)

main :: IO ()
main =
  run 1337 (serve (Proxy @API) server)