Public extensions to the open source akka-http library to support pagination

Akka-http Extensions

Join the chat at Build Status codecov Download

akka-http-extensions its a simple library with useful tools for develop web apps with Akka-http.

This is an updated project that uses Akka-http instead of Spray:


"com.lonelyplanet" %% "akka-http-extensions" % "0.4.13"

You might need to also add our repository:

resolvers ++= Seq(
  Resolver.bintrayRepo("lonelyplanet", "maven")



  • Expires HTTP header support via expires directive
  • Kamon tracing directives - includes support for X-Trace-Token HTTP header and MDC logging
  • Request logger
  • Fallback to default limit and offset parameters in case they are missing
  • Add reasonable defaults for exception and rejection handling


  • Pagination support


Exception Handling

The trait ExceptionHandling offers a reasonable defaults for exception and rejection handling.
The response type is a ErrorMessage which additionally transformed to JsonAPI format.
The ID of the exception is extracted from X-Trace-Token header

Example usage (after extending trait ExceptionHandling):

val routing = Route.seal {
  optionalHeaderValueByName("x-trace-token") { traceToken =>
    withRequestTimeoutResponse(request => timeoutResponse(traceToken)) {

Pagination Support

The trait PaginationDirectives offers some helpers for handling pagination:

path("filter-test") {
  withOptionalPagination { page =>
    complete {
      page match {
        case Some(page) => ... // A page was requested
        case None => ... // No page was requested

Alternatively you can use:

path("filter-test") {
  withPagination { page =>
    complete {
      // page is always set

The page object has this format

sealed trait Order

object Order {
  case object Asc extends Order
  case object Desc extends Order

case class PageRequest(index: Int, size: Int, sort: Map[String, Order])

This is an example of url: /filter-test?page=1&size=10 or /filter-test?page=1&size=10&sort=name,asc;age,desc

The name of the parameters can be configured through Typesafe Config:

akka.http {
    extensions {
            index-param-name = "page"
            size-param-name  = "size"
            sort-param-name  = "sort"
            asc-param-name   = "asc"
            desc-param-name  = "desc"
            sorting-separator = ";"
            order-separator  = ","
            defaults {
                enabled = true
                always-fallback = true
                offset = 10
                limit = 10


We use bintray-sbt plugin for publishing artifacts, to publish newer version of the library run:

sbt publish

That's all what is required