Home

spray

spray is a lightweight Scala framework for building RESTful web services on top of Akka. It sports the following main features:

• Completely asynchronous, non-blocking, actor-based request processing for efficiently handling very high numbers of concurrent connections
• Powerful, flexible and extensible internal Scala DSL for declaratively defining your web service behavior
• Immutable model of the HTTP protocol, decoupled from the underlying web server / servlet container
• Full testability of your REST services, without the need to fire up containers or actors

Apart from a server module spray also has a client component for easy consumption of REST APIs (spray-client) and a JSON module (spray-json).

The latest release is 0.7.0, which is built against Scala 2.9.0-1 and Akka 1.1.x (see Requirements for more information).

Very Basic spray-server Example

import cc.spray._

trait HelloService extends Directives {
  val helloService = {
    path("hello") {
      get { _.complete(<h1>Say hello to Spray</h1>) }
    }
  }
}

Latest Blog Posts

• spray 0.7.0 released
• Introducing spray - RESTful web services on top of Akka

Support, Feedback, General Discussion

Please use the http://groups.google.com/group/spray-user/ mailing list!
You should also follow us on twitter: @spraycc

Longer Sample Code

The following is a spray-server web service definition that tries to show off as many of sprays features as possible. The resulting service does not really do anything useful but its definition should give you a pretty good idea of what is possible with spray:

val service = {
  path("orders") {
    authenticate(httpBasic(realm = "admin area")) { user =>
      get {
        cache {
          encodeResponse(Deflate) {
            // marshal custom object with in-scope marshaller
            _.complete(getOrdersFromDB())
          }
        }
      } ~
      post {
        (decodeRequest(Gzip) | decodeRequest(NoEncoding)) {
          // unmarshal with in-scope unmarshaller
          content(as[Order]) { order =>
            // transfer to newly spawned actor
            detach { ctx =>
              // ... write order to DB
              ctx.complete("Order received")
            }
          }
        }
      }
    }
  } ~
  // extract URI path element as Int
  pathPrefix("order" / IntNumber) { orderId =>
    path("") {
      // method tunneling via query param
      (put | parameter('method ! "put")) {
        content(as[Order]) { order => ctx =>
          // transfer request handling to custom actor
          myDbActor ! Update(order, ctx)
        }
      } ~
      get {
        // JSONP support
        jsonpWithParameter("callback") {
          // use in-scope marshaller to create completer function
          produce(instanceOf(Order)) { complete =>
            _ => complete(getOrderFromDB(orderId))
          }
        }
      }                
    } ~
    path("items") {
      // parameters to case class extraction
      parameters('size as[Int], 'color ?, 'dangerous ? "no")
              .as(instanceOf(OrderItem)) { orderItem =>
        // ... route using case class instance created from
        // required and optional query parameters
      }
    }
  } ~
  path("documentation") {
    // cache responses to GET requests
    cache {
      // serve up static content from a JAR resource
      getFromResourceDirectory("docs")
    }
  }
}

License

spray is released under the Apache License 2.0.

Portions of the immutable HTTP model are
copyright (C) 2010-2011 by the BlueEyes Web Framework Team