jaceklaskowski
Spray, Akka Streams and HTTP - Your Friendly Getting Started

Updated 2 years ago

Spray and Akka HTTP The Getting Started

Welcome to my loose notes about Spray and (more often recently) Akka Streams and HTTP.

Start at Getting Started for the official way to get started with the Spray toolkit. The document ultimately leads to Introduction / Getting Started where you can learn about the Spray templates:

To help you get going we created the spray-template project on GitHub. This provides everything you need to get a spray HTTP server application up-and-running in under 5 minutes and view the result in your browser.

spray Template Project however reads:

This projects provides a starting point for your own spray-routing endeavors. There are 8 branches, providing templates for spray-routing

I usually pick spray-can, Scala 2.11 + Akka 2.3 + spray 1.3 (the on_spray-can_1.3_scala-2.11 branch) and follow the steps in README.md.

Step 1. Clone spray-routing project

Execute git clone https://github.com/spray/spray-template.git spray-routing.

➜  sandbox  git clone https://github.com/spray/spray-template.git spray-routing
Cloning into 'spray-routing'...
remote: Counting objects: 904, done.
remote: Total 904 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (904/904), 111.36 KiB | 125.00 KiB/s, done.
Resolving deltas: 100% (333/333), done.
Checking connectivity... done.

Enter the directory cd spray-routing where you git clone the project:

➜  sandbox  cd spray-routing

All commands should now be executed in the directory - that's the playground for your Spray learning.

➜  spray-routing git:(on_spray-can_1.3_scala-2.11)

Step 2. Execute tests

Run activator (preferred) or sbt command.

Please note that I'm using a custom-built sbt and hence the name xsbt.

➜  spray-routing git:(on_spray-can_1.3_scala-2.11) xsbt
JAVA_HOME=/Library/Java/JavaVirtualMachines/java8/Contents/Home
SBT_OPTS= -Xms512M -Xmx1536M -Xss1M -XX:+CMSClassUnloadingEnabled -Dfile.encoding=UTF-8
[info] Loading global plugins from /Users/jacek/.sbt/0.13/plugins
[info] Loading project definition from /Users/jacek/dev/sandbox/spray-routing/project
[info] Set current project to spray-routing (in build file:/Users/jacek/dev/sandbox/spray-routing/)
[spray-routing]>

While in sbt shell, type in test to download the dependencies of the project to your local repository, and then execute the tests.

[spray-routing]> test
[info] MyServiceSpec
[info]
[info] MyService should
[info] + return a greeting for GET requests to the root path
[info] + leave GET requests to other paths unhandled
[info] + return a MethodNotAllowed error for PUT requests to the root path
[info]
[info] Total for specification MyServiceSpec
[info] Finished in 155 ms
[info] 3 examples, 0 failure, 0 error
[info] Passed: Total 3, Failed 0, Errors 0, Passed 3
[success] Total time: 2 s, completed Mar 12, 2015 9:02:45 AM

Step 3. Run Spray service (using sbt-revolver plugin)

Execute ~ reStart (mind the tilde ~ that watches the source code and triggers the commands that follow it after the code's changes).

[spray-routing]> ~ reStart
[info] Application spray-routing not yet started
[info] Starting application spray-routing in the background ...
spray-routing Starting com.example.Boot.main()
[success] Total time: 0 s, completed Mar 12, 2015 9:04:12 AM
1. Waiting for source changes... (press enter to interrupt)
spray-routing [INFO] [03/12/2015 09:04:13.487] [on-spray-can-akka.actor.default-dispatcher-3] [akka://on-spray-can/user/IO-HTTP/listener-0] Bound to localhost/127.0.0.1:8080

You should now be able to browse http://localhost:8080 using your browser or curl or httpie (wholeheartedly recommended).

➜  spray-routing git:(on_spray-can_1.3_scala-2.11) http localhost:8080
HTTP/1.1 200 OK
Content-Length: 149
Content-Type: text/html; charset=UTF-8
Date: Thu, 12 Mar 2015 08:05:42 GMT
Server: spray-can/1.3.2

<html>
              <body>
                <h1>Say hello to <i>spray-routing</i> on <i>spray-can</i>!</h1>
              </body>
            </html>

For this particular example, using the browser is going to give you a more pleasant experience as the only route offered is accessing the root / using http://localhost:8080.

Step 4. Start hacking!

Use src/main/scala/com/example/MyService.scala as a starting point.

The complete MyService trait is copied here to complete the introduction.

trait MyService extends HttpService {

  val myRoute =
    path("") {
      get {
        respondWithMediaType(`text/html`) { // XML is marshalled to `text/xml` by default, so we simply override here
          complete {
            <html>
              <body>
                <h1>Say hello to <i>spray-routing</i> on <i>spray-can</i>!</h1>
              </body>
            </html>
          }
        }
      }
    }
}

You're all set! Happy hacking.