Note: To run examples, please make sure that the flag
is enabled in your compiler options (i.e
scalacOptions += "-Ypartial-unification" in sbt).
This is enabled by default in the giter8 template.
Getting started with http4s is easy. Let’s materialize an http4s
skeleton project from its giter8 template:
$ sbt -sbt-version 1.0.2 new http4s/http4s.g8 -b 0.18
$ sbt -sbt-version1.0.2 new http4s/http4s.g8 -b 0.18
Follow the prompts. For every step along the way, a default value is
provided in brackets.
- name of your project.
- the organization you publish under. It’s common practice on the JVM
to make this a domain you own, in reverse order (i.e., TLD first).
io.github.username is also a fine choice.
- by default, your organization followed by the project name.
- the version of SBT for your generated project.
- the version of Scala for your generated project.
- defaults to the latest stable release of http4s. See
the versions page for other suggestions.
- the version of Logback for logging in your generated project.
At the end of the process, you’ll see:
Template applied in ./quickstart
In addition to sbt build machinery, a Scala source files are
$ cd quickstart
$ find . -name '*.scala'
HelloWorldService.scala defines a runnable class by extending
StreamApp[IO] must define a method
requestShutdown: IO[Unit]) which acts the entry point to your application. That
method starts blaze, http4s’ native server backend.
route method defines a simple
HttpService that responds to
/hello/$USERNAME with a JSON greeting. Let’s try it:
$ sbt run
Depending on the state of your Ivy cache, several dependencies will
download. This is a good time to grab a beverage. When you come
back, you should see a line similar to this:
264 [run-main-0] INFO org.http4s.blaze.channel.nio1.NIO1SocketServerGroup - Service bound to address /127.0.0.1:8080
This indicates that blaze is running our service on port 8080. Let’s try out the
hello world service with curl:
$ curl -i http://localhost:8080/hello/world
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Date: Thu, 01 Dec 2016 05:05:24 GMT
To shut down your server, simply press
^C in your console. Note that
when running interactive SBT,
^C will kill the SBT process. For rapid
application development, you may wish to add the sbt-revolver plugin
to your project and starting the server from the SBT prompt with
With just a few commands, we have a fully functional app for creating
a simple JSON service.