Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Fast, testable, Scala services built on Twitter-Server and Finagle
Scala Python Java Other
Latest commit 4e881fd @cacoco cacoco committed with jenkins examples - Update finatra/examples logback configuration
The examples all hardcode filenames even though logback supports
being able to parameterize configuration via setting System
properties. We don't show this utility in the examples as we did
not want users to NEED to set the -D args.

Update the examples logback configurations to allow setting the
filenames via -D args with defaults in the cases where the -D
args are not passed.

More dynamic logback configuration and better examples.

Failed to load latest commit information.
benchmarks Rename finagle-httpx to finagle-http
bin Modify Finatra to work with develop branch
examples examples - Update finatra/examples logback configuration
http Add more validation when deserializing json arrays Problem: Elements …
httpclient finatra - change EmbeddedTwitterServer to accept a base com.twitter.s…
inject-thrift-client-http-mapper finatra: Publish inject-thrift-client-http-mapper
inject finatra: Change startupFailedThrowable to volatile var in EmbeddedApp
jackson Add more validation when deserializing json arrays Problem: Elements …
project Modify Finatra to work with develop branch
slf4j Improve test coverage
thrift finatra: Stat the causes of failed HTTP requests
utils finatra: Stat the causes of failed HTTP requests
.gitignore Move finatra/examples code to be based on unpublished source for sbt …
.travis.yml Update TravisCI to use develop branch finatra-http: Prevent regexes in string routes and optimize route mat… finatra - Update to 2.1.2-SNAPSHOT Updates post 2.1.1 release. Update
LICENSE Add and update files for open-repository finatra - change EmbeddedTwitterServer to accept a base com.twitter.s…
build.sbt finatra: Stat the causes of failed HTTP requests
finatra_logo.png Added transparent logo and updated
sbt finatra - revert to deprecated `com.twitter.concurrent.exp.AsyncStream`


Fast, testable, Scala services built on Twitter-Server and Finagle

finatra logo

Build Status Test Coverage

Maven Central



  • Production use as Twitter’s HTTP framework
  • ~50 times faster than v1.6 in several benchmarks
  • Powerful feature and integration test support
  • Optional JSR-330 Dependency Injection using Google Guice
  • Jackson based JSON parsing supporting required fields, default values, and custom validations
  • Logback MDC integration with com.twitter.util.Local for contextual logging across futures


Check out our list of recent presentations: Finatra Presentations


  • Finatra is now built against the latest Finagle v6.30.0 and Twitter Server v1.15.0 releases.
  • Please take a look at our new User Guide!
  • Keep up with the latest news here on our blog.

Quick Start

To get started we'll focus on building an HTTP API for posting and getting tweets:


case class TweetPostRequest(
  @Size(min = 1, max = 140) message: String,
  location: Option[TweetLocation],
  nsfw: Boolean = false)

case class TweetGetRequest(
  @RouteParam id: TweetId)

Then, let's create a Controller:


class TweetsController @Inject()(
  tweetsService: TweetsService)
  extends Controller {

  post("/tweet") { requestTweet: TweetPostRequest =>
    for {
      savedTweet <-
      responseTweet = TweetResponse.fromDomain(savedTweet)
    } yield {

  get("/tweet/:id") { request: TweetGetRequest =>

Next, let's create a server:


class TwitterCloneServer extends HttpServer {
  override val modules = Seq(FirebaseHttpClientModule)

  override def configureHttp(router: HttpRouter): Unit = {

And finally, we can write a Feature Test:

Feature Test

class TwitterCloneFeatureTest extends FeatureTest with Mockito {

  override val server = new EmbeddedHttpServer(new TwitterCloneServer)

  @Bind val firebaseClient = smartMock[FirebaseClient]

  @Bind val idService = smartMock[IdService]

  "tweet creation" in {
    //Setup mocks
    idService.getId returns Future(StatusId("123"))

    val tweetResponse = TweetResponse(...)
    firebaseClient.put("/tweets/123.json", tweetResponse) returns Future.Unit
    firebaseClient.get("/tweets/123.json")(manifest[TweetResponse]) returns Future(Option(tweetResponse))

    //Assert tweet post
    val result = server.httpPost(
      path = "/tweet",
      postBody = """
          "message": "Hello #FinagleCon",
          "location": {
            "lat": "37.7821120598956",
            "long": "-122.400612831116"
          "nsfw": false
      andExpect = Created,
      withJsonBody = """
          "id": "123",
          "message": "Hello #FinagleCon",
          "location": {
            "lat": "37.7821120598956",
            "long": "-122.400612831116"
          "nsfw": false

      path = result.location.get,
      andExpect = Ok,
      withJsonBody = result.contentString)

  "Post bad tweet" in {
      path = "/tweet",
      postBody = """
          "message": "",
          "location": {
            "lat": "9999"
          "nsfw": "abc"
      andExpect = BadRequest,
      withJsonBody = """
          "errors" : [
            "message: size [0] is not between 1 and 140",
            " [9999.0] is not between -85 and 85",
            "location.long: field is required",
            "nsfw: 'abc' is not a valid boolean"

Detailed Documentation

The Finatra project is composed of several libraries. You can find details in a project's README or see the User Guide for detailed information on building applications with Finatra.

Example Projects

For more detailed information see the within each example project.


A barebones "Hello World" service.


A barebones service that is deployable to Heroku.


A url shortening example that is deployable to Heroku.


An example Twitter-like API for creating and retrieving Tweets.


A server used for benchmarking performance compared to a raw finagle-http service.


A proof-of-concept streaming JSON service.


A full list of contributors can be found on GitHub.

Follow @finatra on Twitter for updates.


Copyright 2015 Twitter, Inc.

Licensed under the Apache License, Version 2.0:

Something went wrong with that request. Please try again.