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

• 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 can 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") {
    get {
      // marshal custom object with in-scope marshaller
      _.complete(getOrdersFromDB())
    } ~
    post {
      // unmarshal with in-scope unmarshaller
      contentAs[Order] { order =>
        // transfer to newly spawned actor
        detached { ctx =>
          // ... write order to DB
          ctx.complete("Order received")
        }
      }
    }
  } ~
  // use regex to extract URI element
  pathPrefix("order" / "\\\\d+".r) { orderId =>
    path("") {
      // method tunneling via query param
      (put | parameter('method ! "put")) {
        contentAs[Order] { order => ctx =>
          // transfer request handling to custom actor
          myDbActor ! Update(order, ctx)
        }
      } ~
      get {
        // use in-scope marshaller to create completer function
        produces[Order] { complete =>
          _ => complete(getOrderFromDB(orderId))
        }
      }                
    } ~
    path("items") {
      parameters('size, 'color ?, 'dangerous ? "no") {
        (size, color, dangerous) =>
        // ... route using required and optional query parameters  
      }
    }
  } ~
  path("documentation") {
    // cache responses to GET requests
    cached {
      // 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