Rapture is a general-purpose library written in Scala. It implements a wide range of features like JSON interop, support for HTTP, general I/O, HTML etc.

Most important feature of Rapture is its very simple and intuitive API. From a perspective of a Clojure developer (that’s me) it’s the best library in Scala ecosystem — can do a lot, is easy to learn and easy to use.

Unfortunately it lacks a documentation and source code under the hood is not beginner-friendly.

Twitch — Rapture — Gist

I created a very simple project which does the following:

Fetch a list of top games on Twitch using their REST API.

Convert a received JSON to instances of Scala objects.

Prepare a new JSON which will be used to create a new gist on Github.

Create a new gist via a Github REST API.

The project is available on Github.

You can read a bit more to see how to work with JSON and HTTP using on Rapture website.

In order to run code snippets from this blog post just checkout my project, launch SBT console and run this code:

HTTP requests — GET

This is the simplest way of making a GET request. Just create a HTTP query using uri macro and fetch data from provided URL. It cannot be easier.

Do the same but provide query params in a much more convenient way.

Modes — powerful higher order functions

Modes are basically wrappers around library methods which can execute some operations before and after the original method; they can change its return type etc. They provide similar functionality to Ring middleware or Play filters. (However, afaik Play filters cannot be easily composed to create new filters.)

Default mode is to do nothing special:

To make dealing with failures easier we can use returnTry mode:

If we need concurrency, we can have it right away:

There are a few bits of documentation about modes on rapture.io website. Source code is available here.

Parsing JSON

Rapture has been the best Scala library for parsing JSON for me so far. It allows to map JSON to instances of Scala case classes without absolutely any boilerplate or very easily access selected fields in JSON object using features of a Dynamic trait.

So, we have our data:

Which has the following format:

See Twitch API docs for more information.

Mapping JSON to instances of case classes

Let’s map our data to an instance of a TopGames case class:

There are a few interesting things to mention here.

First of all, it just works. There was no need to define serializers, use jsonFormat3 methods or other boilerplate required by other JSON libraries.

Second, take a look at top field in TopGames class. It has a Json type and not another deeply nested structure of instances of case classes.

Third, httpQueryExtractor shows how to map JSON output to custom types (in this case to HttpQuery).

Accessing JSON values

Json implements a Dynamic trait which allows to access data in JSON almost in almost a dynamically typed manner. Being a Clojure developer, I really appreciate this feature.

Let’s find the name of a second most popular game on Twitch:

It compiles and works as expected because Json implements Scala’s Dynamic type

You can read more about working with JSON on rapture.io website.

Modes can be used to enhance functionality of JSON functions. So, you can use modes.returnTry._ if input String might not necesarily be a valid JSON or modes.returnFuture._ if parsing takes a lot of CPU. Or, you can compose these modes together.

Generating JSON

We are going to create a gist file using Github REST API.

Let’s prepare a JSON.

There are two formatters which define how Json object should be converted to a String.

Human readable format:

Compact format:

Http request — POST

Now we are ready to create a gist. To use HTTP verb other then GET we need to use one of httpVERB methods.

Final step — extract URL pointing to a created gist from a HTTP response.

That’s all.. for now

I hope that Rapture will soon get wider adoption in Scala community. It definitely deserves that.