Finch.io is a library for building REST APIs in Scala using Finagle. It allows for composable endpoints and services. Parameters can be extracted from requests using a reader monad. Requests and responses can be validated. Responses can be JSON, plain text, or other formats. Authentication such as basic auth can also be supported. The documentation provides examples of defining endpoints and services, composing them, handling parameters and validation, and constructing different response types including JSON.

1. Finch.io
Purely Functional REST API
with Finagle
Vladimir Kostyukov
http://vkostyukov.ru

2. http://github.com/finagle/finch
2

3. Finch.io: Quickstart
1 def hello(name: String) = new Service[HttpRequest, HttpResponse] = {
2 def apply(req: HttpRequest) = for {
3 title <- OptionalParam("title")(req)
4 } yield Ok(s"Hello, ${title.getOrElse("")} $name!")
5 }
6
7 val endpoint = new Endpoint[HttpRequest, HttpResponse] {
8 def route = {
9 // routes requests like '/hello/Bob?title=Mr.'
10 case Method.Get -> Root / "hello" / name => hello(name)
11 }
12 }
3

4. Finch.io Overview
• Composable Endpoints
• Composable Microservices
• Request Reader
• Response Builder
• JSON
• OAuth2, Basic Auth
4

5. Endpoints
1 val a = new Endpoint[HttpRequest, HttpResponse] {
2 def route = {
3 case Method.Get -> Root / "bob" => Redirect("/users/bob")
4 case Method.Get -> Root / "users" / Long(id) => GetUser(id)
5 }
6 }
7
8 val b = new Endpoint[HttpRequest, HttpResponse] {
9 def route = {
10 case Method.Get -> Root / "tickets" => GetTickets
11 }
12 }
13
14 val c: Endpoint[HttpRequest, HttpResponse] = a orElse b
15 val d: Service[HttpRequest, HttpResponse] = c.toService
5

6. Composing services & endpoints
1 val ab: Filter[A, C, B, C] = ???
2 val bc: Endpoint[B, C] = ???
3 val cd: Service[C, D] = ???
4
5 val ad: Endpoint[A, D] = ab ! bc ! cd
6

7. Case Study: Feedbacks Endpoint
1 object Feedback extends Endpoint[OAuth2Request[OAuthUser], JsonResponse] {
2 def route = {
3 case Method.Get -> Root / "users" / Long(id) / "feedbacks" =>
4 GetUserFeedbacks(id) !
5 JoinInnerArrays("attachments") !
6 TakeAll
7
8 case Method.Put -> Root / "orders" / Long(id) / "feedback" =>
9 ByUserId(MakeSureUserCanPutOrderFeedback(_, id)) !
10 MakeSureThereIsNoOrderFeedbacks(id) !
11 MakeSureOrderIsCompleted(id) !
12 PutOrderFeedback(id) !
13 ByLocation(UpdateServiceRating) !
14 ByLocation(SendFeedbackSubmittedMail) !
15 ByLocation(GetFeedback) !
16 TakeFirst
17 }
18 }
7

8. Params (Reader Monad)
1 val user = for {
2 name <- RequiredParam("name")
3 age <- RequiredIntParam("age")
4 city <- OptionalParam("city")
5 } yield User(name, age, city.getOrElse("Novosibirsk"))
6
7 val service = new Service[HttpRequest, JsonResponse] {
8 def apply(req: HttpRequest) = for {
9 u <- user(req)
10 } yield JsonObject(
11 "name" -> u.name,
12 "age" -> u.age,
13 "city" -> u.city
14 )
15 }
16
17 val u: Future[User] = user(request) handle {
18 case e: ParamNotFound => BadRequest(e.param)
19 }
8

9. Case Study: Pagination
1 val pagination = {
2 val outerLimit = Config[Int]("limit", 15)
3
4 for {
5 offset <- OptionalIntParam("offset")
6 limit <- OptionalIntParam("limit")
7 } yield (
8 offset.getOrElse(0),
9 math.min(limit.getOrElse(outerLimit), outerLimit)
10 )
11 }
12
13 val a = new Service[HttpRequest, HttpResponse] {
14 def apply(req: HttpRequest) = for {
15 (offset, limit) <- pagination(req)
16 } yield Ok(s"offset $offset, limit $limit")
17 }
9

10. Multi-Value Params
1 val reader = for {
2 a <- RequiredIntParams("a")
3 b <- RequiredIntParams("b")
4 } yield (a, b)
5
6 // request("a=1,2,3&b=4&b=5")
7 val (a, b): (List[Int], List[Int]) = reader(request)
8 // a = List(1, 2, 3)
9 // b = List(4, 5)
10

11. Validation
1 val adult = for {
2 u <- user
3 _ <- ValidationRule("age", "should be greater then 18") { user.age >= 18 }
4 } yield u
5
6 val user: Future[User] = adult(request) handle {
7 case e: ParamNotFound =>
8 BadRequest(JsonObject("param" -> e.param))
9 case e: ValidationFailed =>
10 BadRequest(JsonObject("param" -> e.param, "rule" -> e.rule))
11 }
11

12. Responses
1 // an empty response with status 200
2 val a = Ok()
3
4 // 'plain/text' response with status 404
5 val b = NotFound("body")
6
7 // 'application/json' response with status 201
8 val c = Created(JsonObject("id" -> 42))
9
10 // 'plain/text' response of status 403 with custom header
11 val d = Forbidden.withHeaders("Some-Header-A" -> "a")("plain")
12

13. JSON
1 // a : {
2 // b : 10,
3 // c : 20,
4 // d : 30
5 // }
6 val a = JsonObject("a.b" -> 10, "a.c" -> 20, "a.d" -> 30)
7
8 // a : {
9 // a : 100,
10 // b : 200
11 // }
12 val b = JsonObject("a.a" -> 100, "a.b" -> 200)
13
14 // a : {
15 // a : 100
16 // b : 200,
17 // c : 20,
18 // d : 30
19 // }
20 val c = JsonObject.mergeRight(a, b)
13

14. Basic Auth
1 object ProtectedUser extends Endpoint[HttpRequest, HttpResponse] {
2 def route = {
3 case Method.Get -> Root / "users" =>
4 BasicallyAuthorize("user", "password") !
5 GetUsers
6 }
7 }
14

15. Further Steps
• Lightweight in-memory caching
• Better JSON
15

16. References
§ http://twitter.github.io/finagle/
!
§ https://github.com/finagle/finch
!
§ https://github.com/finagle/finagle-oauth2
16

17. Stay Finagled!
!
And drop your feedbacks to
@vkostyukov
17