spray: REST on Akka (Scala Days)

REST on Akka
Scala Days
April 17th, 2012

What is spray?
Vision: Provide the best toolkit for REST/HTTP
and low-level network-IO on top of Akka

What is spray?
• First released about 1 year ago

What is spray?
• Principles: lightweight, async, non-blocking,
actor-based, modular, few deps, testable

What is spray?
• Principles: lightweight, async, non-blocking,
actor-based, modular, few deps, testable
• Philosophy: set of libraries, not framework

Current State
Transitioning from Akka 1.3 to Akka 2.0

Current State
• spray 0.9.0 for Akka 1.3 released in March

Current State
• spray 1.0-M1 for Akka 2.0 two weeks ago

Current State
• Next: second milestone of spray 1.0

Current State
• Next: second milestone of spray 1.0
Focus of this talk

Components
spray-routing spray-client

spray-servlet spray-can spray-json

spray-http spray-io

Components


spray-http spray-io
Low-level, “actorized”
network IO

Components


spray-http spray-io
rich immutable HTTP
model (no Akka)

Components

low-level HTTP
server and client
spray-http spray-io

Components

Servlet API
adapter layer
spray-http spray-io

Components
DSL for server-side
API construction

spray-http spray-io

Components
Complementary high-
level HTTP client

spray-http spray-io

Components

straight JSON in
Scala (no Akka)
spray-http spray-io

Components
Focus for the
rest of the talk

spray-http spray-io

spray-routing
• Runs on spray-servlet or spray-can

spray-routing
• Tool for building a “self-contained” API layer

spray-routing
• Central element:
Routing DSL for deﬁning web API behavior

spray-routing
• Central element:
Routing DSL for deﬁning web API behavior
• Focus: RESTful web API, not web GUI

Basic Architecture
Application

Business
Logic

Basic Architecture
REST API layer Application

Routing
Logic Business
Logic

Basic Architecture

HTTP Request

Routing
Logic Business
Logic

Basic Architecture

HTTP Request Action

Routing
Logic Business
Logic

Basic Architecture

HTTP Request Action

domain
Routing object ! Business
Logic
Logic

Basic Architecture

HTTP Request Action

domain
Logic
Logic

Reply

Basic Architecture

HTTP Request Action

domain
Logic
Logic

HTTP Response Reply

API Layer Responsibilities
• Request routing based on method, path,
query parameters, entity

• (Un)marshalling to / from domain objects

• Encoding / decoding (compression)

• Authentication / authorization

• Caching and serving static content

• Caching and serving static content
• RESTful error handling

API Building in spray
• HTTP messages are actor messages

class PingServiceActor extends Actor {
def receive = {
case HttpRequest(GET, "/ping", _, _, _) =>
sender ! HttpResponse(200, "PONG")
}
}

def receive = {
}
}

• Could build services only via pattern-matching

def receive = {
}
}

• Could build services only via pattern-matching
• But: pattern-matching becomes awkward for
more complex service deﬁnitions

API Building in spray: DSL
Simple example:
class MyServiceActor extends Actor with Routing {
def receive = receiveFromRoute {
path("order" / HexIntNumber) { id =>
get {
completeWith {
"Received GET request for order " + id
}
} ~
put {
completeWith {
"Received PUT request for order " + id
}
}
}
}
}

sprays Routing DSL
• Built from recombinant elements called
“directives”

sprays Routing DSL
“directives”
• Concise, readable, maintainable

sprays Routing DSL
“directives”
• Highly composable

sprays Routing DSL
“directives”
• Type-safe

sprays Routing DSL
“directives”
• Type-safe
• Easily extensible with custom constructs

sprays Routing DSL
“directives”
• Type-safe
• Easily extensible with custom constructs
• Directly interfaces with Akka API

Routing Basics
Routes in spray:
type Route = RequestContext => Unit

Routing Basics
Routes in spray:
type Route = RequestContext => Unit Explicit
continuation-
passing style

Routing Basics
Routes in spray:
type Route = RequestContext => Unit Explicit
continuation-
passing style
Central object:
case class RequestContext(
request: HttpRequest,
...) {
  def complete(...) { ... }
  def reject(...) { ... }
  ...
}

Routing Basics
The simplest route:
ctx => ctx.complete("Say hello to spray")

Routing Basics
The simplest route:

or:
_.complete("Say hello to spray")

Routing Basics
The simplest route:

or:

or using a “directive”:
completeWith("Say hello to spray")

Routing Basics
The simplest route:

or:

or using a “directive”:
completeWith("Say hello to spray")

def completeWith[T :Marshaller](value: => T): Route =
_.complete(value)

Directives
Route structure built with directives:

val route: Route =
get {
completeWith {
}
}~
put {
completeWith {
}
}
}

Directives

val route: Route =
get {
completeWith {
}
directive
}~
name put {
completeWith {
}
}
}

Directives

val route: Route =
get {
completeWith {
}
}~
args
put {
completeWith {
}
}
}

Directives

val route: Route =
get { extractions
completeWith {
}
}~
put {
completeWith {
}
}
}

Directives

val route: Route =
get {
completeWith {
}
}~
put {
completeWith {
}
} inner route
}

Directives

val route: Route =
get {
completeWith {

}~
} route concatenation:
put { recover from rejections
completeWith {
}
}
}

Directives

val route: Route =
get {
completeWith {
}
}~
put {
completeWith {
}
} Route structure
}
forms a tree!

Directives
spray 0.9.0 comes with 69 predefined directives:
alwaysPass, authenticate, authorize, autoChunk, cache, cacheResults, clientIP,
completeWith, content, cookie, decodeRequest, delete, deleteCookie, detach,
dynamic, encodeResponse, filter, filter1, filter2, filter3, filter4, filter5, filter6,
filter7, filter8, filter9, formField, formFields, get, getFromDirectory, getFromFile,
getFromFileName, getFromResource, getFromResourceDirectory, handleWith,
hardFail, head, headerValue, headerValuePF, host, jsonpWithParameter, method,
optionalCookie, options, parameter, parameters, path, pathPrefix, post,
produce, provide, put, redirect, reject, respondWithContentType,
respondWithHeader, respondWithHeaders, respondWithMediaType,
respondWithStatus, setCookie, trace, transformChunkedResponse,
transformRejections, transformRequest, transformRequestContext,
transformResponse, transformRoute, transformUnchunkedResponse, validate

Real World Example
lazy val route = {
encodeResponse(Gzip) {
path("") {
get {
redirect("/doc")
}
}~
pathPreﬁx("api") {
jsonpWithParameter("callback") {
path("top-articles") {
get {
parameter('max.as[Int]) { max =>
validate(max >= 0, "query parameter 'max' must be >= 0") {
completeWith {
(topArticlesService ? max).mapTo[Seq[Article]]
}
}
}
}
}~
tokenAuthenticate { user =>
path("ranking") {
get {
countAndTime(user, "ranking") {
parameters('ﬁxed ? 0, 'mobile ? 0, 'sms ? 0, 'mms ? 0,

}
}

}~
}
}
Real World Example
tokenAuthenticate { user =>
path("ranking") {
get {
countAndTime(user, "ranking") {
parameters('ﬁxed ? 0, 'mobile ? 0, 'sms ? 0, 'mms ? 0,
'data ? 0).as(RankingDescriptor) { descr =>
(rankingService ? Ranking(descr)).mapTo[RankingResult]
}
}
}
}~
path("accounts") {
post {
authorize(user.isAdmin) {
content(as[AccountDetails]) { details =>
(accountService ? NewAccount(details)).mapTo[OpResult]
}
}
}
}~
path("account" / IntNumber) { accountId =>
get { ... } ~
put { ... } ~
delete { ... }
}
}
}~
pathPreﬁx("v1") {

}
}~

Real World Example
path("account" / IntNumber) { accountId =>
get { ... } ~
put { ... } ~
delete { ... }
}
}
}~
pathPreﬁx("v1") {
proxyToDjango
}
}~
pathPreﬁx("doc") {
respondWithHeader(`Cache-Control`(`max-age`(3600))) {
transformResponse(_.withContentTransformed(markdown2Html)) {
getFromResourceDirectory("doc/root",
pathRewriter = appendFileExt)
}
}
}~
}~
cacheIfEnabled {
encodeResponse(Gzip) {
getFromResourceDirectory("public")
}
}
}

Best Practices
• Keep route structure clean and readable,
pull out all logic into custom directives

Best Practices
• Don’t let API layer leak into application

Best Practices
• Use (Un)marshalling infrastructure

Best Practices
• Use (Un)marshalling infrastructure
• Use sbt-revolver + JRebel for fast dev turn-
around

There is more ...
• SprayJsonSupport, LiftJsonSupport,
TwirlSupport, ScalateSupport

There is more ...
• Asynchronous response push streaming

There is more ...
• Testing spray routes

There is more ...
• RESTful errors

There is more ...
• RESTful errors
• spray-client

There is more ...
• RESTful errors
• spray-client
• spray-io

What’s next?
• release 1.0 featuring improved and simpliﬁed
API for Akka 2.0

What’s next?
API for Akka 2.0
• Better and deeper documentation
(follow Akkas model of treating docs as code)

What’s next?
API for Akka 2.0
• Coming features: deeper REST support,
monitoring, request throttling, ...

What’s next?
API for Akka 2.0
• Coming features: deeper REST support,
monitoring, request throttling, ...
• Possibly: websockets, SPDY

Getting started
• Main site & documentation:
https://github.com/spray/spray/wiki
• Mailing list:
http://groups.google.com/group/spray-user
• Twitter:
@spraycc

Route Example
A simple spray route:

val route: Route =
get {
completeWith {
}
}~
put {
completeWith {
}
}
}

Directives
DRYing up with the `|` operator:

val route =
(get | put) { ctx =>
ctx.complete("Received " + ctx.request.method +
" request for order " + id)
}
}

Directives
Pulling out a custom directive:

val getOrPut = get | put

val route =
getOrPut { ctx =>
}
}

Directives
The `&` operator as alternative to nesting:

val getOrPut = get | put

val route =
(path("order" / HexIntNumber) & getOrPut) { id =>
ctx =>
}

Directives
Pulling out once more:

val orderGetOrPut =
path("order" / HexIntNumber) & (get | put)

val route =
orderGetOrPut { id => ctx =>
}

Directives
Operators are type-safe:
val orderPath = path("order" / IntNumber)

Directives
Compiles?

Directives
Compiles?

val dir = orderPath | get

Directives
Compiles?


val dir = orderPath | path("[^/]+".r / DoubleNumber)

Directives
Compiles?



val dir = orderPath | parameter('order.as[Int])

Directives
Compiles?




val order = orderPath & parameters('oem, 'expired ?)

Directives
Compiles?




val order = orderPath & parameters('oem, 'expired ?)

val route = order { (orderId, oem, expired) =>
... // inner route
}

Proxying with spray
Combining with spray-client to build a proxy:
val conduit = new HttpConduit("target.example.com", 8080)

lazy val proxyToTarget: Route = { ctx =>
ctx.complete {
conduit.sendReceive {
ctx.request.withHeadersTransformed {
_.ﬁlter(_.name != "Host")
}
}.map {
_.withHeadersTransformed {
_.ﬁlter(_.name != "Date")
}
}
}

spray: REST on Akka (Scala Days)

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

En vedette

En vedette (20)

Similaire à spray: REST on Akka (Scala Days)

Similaire à spray: REST on Akka (Scala Days) (20)

Dernier

Dernier (20)

spray: REST on Akka (Scala Days)

Notes de l'éditeur