lonelyplanet / akka-http-extensions

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

GitHub

Akka-http Extensions

Join the chat at https://gitter.im/lonelyplanet/akka-http-extensions 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: https://github.com/Jarlakxen/spray-extensions

Downloading

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

You might need to also add our repository:

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

Changelog

0.4

  • 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

0.3

  • Pagination support

Features

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)) {
      myRoutes
    }
  }
}

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 {
        pagination{
            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
            }
        }
    }
}

Publishing

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

sbt publish

That's all what is required