Finch is a thin layer of purely functional basic blocks atop of Finagle for building composable HTTP APIs. Its mission is to provide the developers simple and robust HTTP primitives being as close as possible to the bare metal Finagle API.
Finch uses multi-project structure and contains of the following modules:
finch-core- the core classes/functionsfinch-argonaut- the JSON API support for the Argonaut libraryfinch-jackson- the JSON API support for the Jackson libraryfinch-json4s- the JSON API support for the JSON4S libraryfinch-circe- the JSON API support for the Circe libraryfinch-test- the test support classes/functionsfinch-oauth2- the OAuth2 support backed by the finagle-oauth2 library
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.3"
)- for the
SNAPSHOTversion:
resolvers += Resolver.sonatypeRepo("snapshots")
libraryDependencies ++= Seq(
"com.github.finagle" %% "[finch-module]" % "0.9.4-SNAPSHOT" changing()
)This "Hello World!" example is built with the 0.9.4-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)See examples sub-project for more complete examples.
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
- A comprehensive documentation may be found in the
docs/folder - The latest Scaladoc is available at http://finagle.github.io/finch/docs
- [Despegar] (http://www.despegar.com)
- [Globo.com] (http://globo.com)
- [Glopart] (https://glopart.ru)
- [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
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
The Finch project supports the Typelevel code of conduct and wants all of its channels (Gitter, GitHub, etc.) to be welcoming environments for everyone.
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.