Last week presented which encouraged myself to do the same type of starting tutorial in Finch. ScalaTimes Creating a TODO application using Akka HTTP and Slick , Finch is a project written by people working mostly on Twitter and it is a TypeLevel incubator. What I like the most about Finch is its simplicity by using pure functional programming constructs and highly efficient libraries underneath. Personally, I have used Finch in various small projects and once in a very serious project / environment. I always found it very easy and simplistic even though it is a very capable library. Finch is fast, just look at You will discover that it is the second faster HTTP library written in Scala. How Fast is Finch? Let’s focus now how to create a simple Rest API using Finch. Our file looks like follow: build.sbt We are only adding the the Finch libraries and Circe for JSON serialization/deserialization. Now, we need to create our first endpoint to be served. Let’s start by something very simplistic and then grow from there. First, we can define a endpoint. hello In here, is, in my opinion, the most important construct we are going to find in Finch. Endpoint The idea behind is that it represent a serie of transformations as follows: Endpoint We get a and transform it into some type . Then we apply some business logic to the input in an asynchronous matter just to finalize with another transformation into the desired . Request A Response In our example, our is a which URL is and the business logic to be applied is just returning . Endpoint get hello hello to you! Now, we need to run the server and expose the to be used. hello We have only created an application that we can be executed, and we have create a to connect to then it serves the as a Finagle Service. server localhost:8080 hello Endpoint We can run the application by doing or . Once running we can send a request to the endpoint using our terminal: and we will get back: sbt run java -jar <the application.jar> http localhost:8080/hello Our Storage Service For this example, we are going to use a storage abstraction that can be implemented in multiple ways, in particular we can create one that talks to an in-memory datastore. is the type of objects we are going to be sending and receiving to our API and Storage is the one in charge of saving / retrieving them. Item Our in-memory implementation is as simple as this. Defining TODO Endpoints 1. GET- TODOS Our first endpoint will be that retrieves all items available in the storage. todos We can see how simple that is! It just does a call. This endpoint will respond to URL in our server. storage.getAll GET /todos 2. POST -TODO Now we can define a new endpoint to add todos that will respond at POST /todo This one is a little more interesting to look at. Because it is a we need to extract the from the body of the message. However, there is a gotcha, the cannot be created without an and that is what the function does. In other words, we extract the from the message body and create an object with it and a random . POST Item Item UUID postTodo taskName POST Item UUID The idea is that you don’t need to have a different model without the id to be sent on the requests. Item Then function does not really care about the id, it just add a new to the storage and returns the recently created one (it has its own new id). storage.add(item) Item Once the has been added, we return the recently created one. Item We can test it from our terminal by doing which returns 3. GET -TODO Retrieving a particular is an easy task. We only need the id and then we can ask for the to get it for us. Item storage We can test it by doing: Which returns the same todo we inserted before. Notice that if the item is not in the storage, will return HTTP message back to the client. .fold NotFound 4. DELETE-TODO In the same way we can do deleteTodo We look for the with the given id. If it exists then we delete it. Then we return accordingly using . Item .fold TodoService The entire code looks like this. TodoService Putting Everything Together We need to expose all these s from our application. Finch uses Shapeless to compose s and taking a closer look to the we can see that this composition is happening in the . Endpoint Endpoint TodoService TodoService.api Let’s look how our application can be rewritten to serve the . TodoService Notice that is the combination of every single . .api Endpoint This composition is done using and it is basically saying that the incoming request must match one of the endpoints. Shapeless Conclusions Finch is an HTTP library that presents an easy way to define endpoints and to compose them into a more complex API. Finch allows us to write purely functional code for the web that is able to server request at hight rates.
