1.
ITERATORSI T E R AT O R S @luksow
Practical Akka HTTP
introduction
Łukasz Sowa, XI Tricity Scala User Group

2.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Hi, I'm Łukasz
● Co-founder, dev @ Iterators (https://iterato.rs)
● Highly concurrent & distributed systems (MSA)
● ScalaWAW organizer (please attend!)
● Pizza, beer & football lover
● http://luksow.com
● contact@luksow.com
● @luksow

3.
ITERATORSI T E R AT O R S @luksow
What's in it for you?
● Learn
– What Akka HTTP is
– Key architectural concepts
– When & how to use it
– How does it fit in the Scala ecosystem
● Takeaways
– Beginners: ability to start using Akka HTTP
– Advanced: solid foundations for more exploring

4.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Akka HTTP basics
boring facts

5.
ITERATORSI T E R AT O R S @luksow
Akka HTTP – in definition
● Part of Akka project
● HTTP toolkit (server- and client-side)
● On top of akka-actor & akka-stream
● Streams, reactive, backpressure, blah!
● Not a framework – focus: integration layers
● Multiple levels of abstraction (open API)
● Scalable; max throughput, acceptable latency
● Both for Java & Scala

6.
ITERATORSI T E R AT O R S @luksow
Akka HTTP – in implementation
● Fully asynchronous & non-blocking
● Actor-friendly but focused on higher-level
API
● Lightweight
● Modular, testable
● Based on mature spray.io

7.
ITERATORSI T E R AT O R S @luksow
Akka HTTP – in dates
● Spray.io (2011-03 – 2015-06 ✝?)
– Bad chunked-requests support
– Missing features (ex. websockets)
– Hard to develop & debug
● Spray.io acquired by Typesafe (2013-10)
● First preview - 0.4 (2014-06)
– Very experimental, practically unusable
● 'Good enough for evaluation and production' – 1.0 (2015-07)
– No, not really, still very experimental and lacking
● Five months later - 2.0 (2015-12)
– Oh sorry, we changed some interfaces, have a nice migration!
● Akka 2.4.2-RC3 (2016-02)
– Akka HTTP included in main Akka project, only 'half experimental'

8.
ITERATORSI T E R AT O R S @luksow
Akka HTTP – in parts
● akka-http-core
– Low-level server & client-side HTTP implementation
● akka-http
– High-level API: (un)marshalling, (de)compression, DSL
● akka-http-testkit
– Utilities for testing server-side implementation
● akka-http-spray-json
– Glue-code for (de)serialization from/to JSON with spray-json
● akka-http-xml
– Glue-code for (de)serialization from/to XML with scala-xml

9.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Inside Akka HTTP
HTTP model, server, DSL,
client, (un)marshalling, testkit

10.
I T E R AT O RITERATORSI T E R AT O R S @luksow
HTTP model
● Fully immutable, case-class-based
● Abstraction for most HTTP things (types!)
● Little logic inside
● Lots of predefined types – common media type,
status codes, encodings etc.
● Open for extensions
● Still very efficient parsing & rendering
● Drawback? Your clients and connected services have
to obey the standard (and bugs happen too!)

11.
I T E R AT O RITERATORSI T E R AT O R S @luksow
HTTP model – examples (1)

12.
I T E R AT O RITERATORSI T E R AT O R S @luksow
HTTP model - examples (2)

13.
I T E R AT O RITERATORSI T E R AT O R S @luksow
HTTP model - examples (3)

14.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Serving – the streams way

15.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Serving – the functional way

16.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Serving – the hard way
Flow[ByteString, ByteString, _]

17.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Serving – example
Full example: https://github.com/theiterators/cors-buster

18.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Serving – the nice way

19.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Routing DSL
● Internal domain specific language for
routing
● How most services are actually written
● Layer to the application (business logic)
● Type safe but flexible
● Not just routing – behaviour definition
● Very composable
● Fun, powerful and looks sexy!

20.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Routing DSL - example

21.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Routing DSL – directives (1)
● type Route = RequestContext ⇒
Future[RouteResult]
● abstract class Directive[L]
● def complete(m: ⇒
ToResponseMarshallable): StandardRoute
● def reject(rejections: Rejection*):
StandardRoute
● def fail(error: Throwable):
Future[RouteResult]

22.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Routing DSL – directives (2)
● ~136 predefined directives
● Roles: extracting, filtering, transforming
request or response, side-effecting
● Create your own by composing (| and &
operators) or writing from scratch
● Beaware: it takes time to fully understand
how directives work

23.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Routing DSL – custom directive

24.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Routing DSL – rejections
● Rejections
– Are produced by directives
– Travel down the routing structure
– Can be cancelled
– Must be handled if no route completes request
– Can be extended
– trait RejectionHandler extends (immutable.Seq[Rejection] ⇒
Option[Route])
– Handling rejection = transforming it into response (probably
with some error code etc.)
– Ex. MethodRejection, AuthorizationFailedRejection,
MissingCookieRejection, MissingQueryParamRejection

25.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Routing DSL – failures
● Failures (or exceptions)
– Are triggered by exceptions or fail(...)
– Travel up the routing structre
– Can be handled by handleExceptions
directive or top-level ExceptionHandler
– trait ExceptionHandler extends
PartialFunction[Throwable, Route]
– Can be used to simplify flow (not very nice) –
ex. for validation

26.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Client
● Connection-level client
– Full control over connection and
request/response scheduling
● Host-level client
– Akka manages connection pool to one
specific host
● Request-level
– Akka performs all connection management

27.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Connection-level client
● Stream-based
● Enables
– HTTP persistent connection
– HTTP pipelining

28.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Host-level client
● Stream-based
● Some complexities around pool
configuration and materialization

29.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Request-level client
● Super easy to use
● What you usually need
● Notice request-building DSL!

30.
I T E R AT O RITERATORSI T E R AT O R S @luksow
(Un)marshalling (1)
● Marshalling – high level → low (wire) level
– ToEntityMarshaller[T]
– ToHeadersAndEntityMarshaller[T]
– ToResponseMarshaller[T]
– ToRequestMarshaller[T]
● Unmarshalling – low (wire) level → high level
– FromEntityUnmarshaller[T]
– FromMessageUnmarshaller[T]
– FromResponseUnmarshaller[T]
– FromRequestUnmarshaller[T]
– FromStringUnmarshaller[T]
– FromStrictFormFieldUnmarshaller[T]

31.
I T E R AT O RITERATORSI T E R AT O R S @luksow
(Un)marshalling (2)
● Many predefined (un)marshallers (also for
generic types)
● Extensible
● JSON and XML support in additional
packages
● Type-class approach – implicit resolution
● Cryptic error messages

32.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Testkit
● Very simple and straightforward
● Allows to assert responses returned for
given requests
● Integrates well with specs2, ScalaTest

33.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Everyday Akka HTTP
some additional remarks

34.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Akka HTTP in Scala world (1)
● Again: it's not a framework
● Not a competition for Play
– Akka HTTP is going to be Play's (2.5.X?)
backend
● Competition: Spray.io, Finagle, Scalatra,
Unfiltered?
● Backed by Lightbend (Typesafe)

35.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Akka HTTP in Scala world (2)
● Where it excels
– Integration layers
– Microservices
– Pure REST APIs
● Where it falls short
– Fully-fledged web applications (with server-
side template generation)
– IMO still lacks maturity

36.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Notable community projects
● https://github.com/softwaremill/akka-http-session
● https://github.com/hseeberger/akka-sse
● https://github.com/hseeberger/akka-http-json
● Not too many
● So roll up your sleeves! :)
● But integrates seamlessly with almost anything
● Lots of educational projects exist

37.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Performance
● Spray.io's performance was impressive
– 750K req/sec via Twitter
– More benchmarks by TechEmpower
● Akka HTTP 1.0 was roughly 10x slower
● Akka HTTP 2.4.2-RC2 75% of Spray's perf
– “this is not the end of the performance work,
we have only just begun”
● But those benchmarks, you know…

38.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Conclusions
tldr;

39.
I T E R AT O RITERATORSI T E R AT O R S @luksow
What was skipped?
● Streams stuff (persistent connections,
pipelining, backpressure etc.)
● Low-level internals
● SSL/TLS support
● Very nice Websocket support
● Probably bunch of other important things

40.
I T E R AT O RITERATORSI T E R AT O R S @luksow
What to remember?
● Akka HTTP is (probably) the hottest Scala HTTP toolkit
● Built on very solid foundations
● Features all the building blocks needed for well-
designed HTTP services
● Provides both low- and high-level (DSLs!) interfaces
for almost everything
● Reactive streams included
● Still lacks maturity
● Easy to start with but hard to master
● Fun to use!

41.
I T E R AT O RITERATORSI T E R AT O R S @luksow
How to start?
● Start coding right away
● Have fun
● Discover best practices along the way
● http://doc.akka.io/docs/akka-stream-and-http-experimental/current/scala/http/index.html
● http://doc.akka.io/api/akka-stream-and-http-experimental/2.0.3/
● https://github.com/theiterators/akka-http-microservice + tutorial
● https://github.com/theiterators/reactive-microservices + tutorial
● Lightbend Activator – search akka-http
● https://groups.google.com/forum/#!forum/akka-user
● https://gitter.im/akka/akka
● Sign up for a newsletter on http://luksow.com to get notified about big tutorial I'm preparing

42.
I T E R AT O RITERATORSI T E R AT O R S @luksow
Thanks!
● Łukasz Sowa
● https://iterato.rs
● http://luksow.com
● contact@luksow.com
● @luksow
Questions?