Finch is a thin layer of purely functional basic blocks atop of Finagle for building composable REST APIs. Its mission is to provide the developers simple and robust REST API primitives being as close as possible to the bare metal Finagle API.

Badges

Modules

Finch uses multi-project structure and contains of the following modules:

• finch-core - the core classes/functions
• finch-argonaut - the JSON API support for the Argonaut library
• finch-jackson - the JSON API support for the Jackson library
• finch-json4s - the JSON API support for the JSON4S library
• finch-circe - the JSON API support for the Circe library
• finch-test - the test support classes/functions
• finch-oauth2 - the OAuth2 support backed by the finagle-oauth2 library

Installation

Every Finch module is published at Maven Central. Use the following sbt snippet ...

• for the stable release:

libraryDependencies ++= Seq(
  "com.github.finagle" %% "[finch-module]" % "0.9.0"
)

• for the SNAPSHOT version:

resolvers += Resolver.sonatypeRepo("snapshots")

libraryDependencies ++= Seq(
  "com.github.finagle" %% "[finch-module]" % "0.9.1-SNAPSHOT" changing()
)

Hello World!

This "Hello World!" example is built with the 0.9.1-SNAPSHOT version of finch-core.

import io.finch._
import com.twitter.finagle.Http

val api: Endpoint[String] = get("hello") { Ok("Hello, World!") }

Http.serve(":8080", api.toService)

Performance

We use end-to-end service benchmark to compare performance between bare-bones Finagle service using Jackson for JSON parsing/serialization against Finch service empowered by Circe. Roughly, the Finch + Circe configuration gives the overhead less than 5% in terms of performance and less than 10% in terms of allocations, compared to Finagle + Jackson.

GET /JSON-Object

Benchmark                                        Mode  Cnt          Score        Error   Unit

FinchCirce.getJsonObj                            avgt   10        352.658 ±     49.267  ms/op
FinchCirce.getJsonObj:·gc.alloc.rate.norm        avgt   10  366909071.657 ±  19659.934   B/op
FinagleJackson.getJsonObj                        avgt   10        372.074 ±     57.819  ms/op
FinagleJackson.getJsonObj:·gc.alloc.rate.norm    avgt   10  328441359.200 ±  78088.424   B/op

POST /JSON-Object

Benchmark                                        Mode  Cnt      Score            Error   Unit

FinchCirce.postJsonObj                           avgt   10        243.935 ±     29.455  ms/op
FinchCirce.postJsonObj:·gc.alloc.rate.norm       avgt   10  399187222.400 ±  84523.131   B/op
FinagleJackson.postJsonObj                       avgt   10        235.564 ±     46.433  ms/op
FinagleJackson.postJsonObj:·gc.alloc.rate.norm   avgt   10  376365652.800 ± 169854.875   B/op

Demo

See very minimalistic Finch application implementing an HTTP backed for TodoMVC.

Documentation

• A comprehensive documentation may be found in the docs/ folder
• The latest Scaladoc is available at http://finagle.github.io/finch/docs

Adopters

• [Despegar] (http://www.despegar.com)
• [Globo.com] (http://globo.com)
• [Hotel Urbano] (http://www.hotelurbano.com)
• Konfettin
• JusBrasil
• Sabre Labs
• Spright
• [SoFi] (https://www.sofi.com/)
• [Qubit] (http://www.qubit.com)
• [QuizUp] (http://www.quizup.com)
• Submit a pull-request to include your company/project into the list

Contributing

There are plenty of ways to contribute into Finch:

• Give it a star
• Join the Gitter room and leave a feedback or help with answering users' questions
• Submit a PR (there is an issue label "easy" for newcomers)
• Be cool and wear a Finch T-Shirt

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.