sttp — an open-source library with simple, type-safe API for defining HTTP requests

The Scala HTTP client that you always wanted!

sttp is an open-source library which provides simple, type-safe API for defining HTTP requests. We’ve asked Adam Warski about the background of this project and why Scala ecosystem needs it.

1. Could you briefly describe what does the sttp library do — what problem is this library trying to solve?

The sttp client provides a programmer-friendly API for describing and sending HTTP requests: a task that is very common in everyday programming. The API aims to be simple and readable, and at the same time “functional” and reasonably type-safe.

sttp client wraps a number of HTTP client libraries, thus integrating easily with a variety of application stacks. Thus, you can use the same API when you use Akka, Monix, cats-effect, zio, or just want to do a couple of synchronous, exploratory requests.

2. How did you or your team come up with an idea for sttp?

There’s a couple of great implementations of the HTTP stack, both in Scala and Java, such as akka-http, http4s, async-http-client and OkHttp. However, their Scala interface is either too low-level or too complicated for the usually simple task of sending HTTP requests. That’s where I think we can do better: the low-level implementations are great; but the programmer-facing API needed improvements. Hence, the sttp client projects provides this better API, wrapping other, existing and tested HTTP clients.

3. Why did you decide to engage in developing this open-source project?

As is often the case, we simply needed this kind of API quite often in our projects. As we couldn’t find anything that would meet our needs, we wrote our own. So this is a typical scratch your itch situation.

4. Is there anything specific that you learned through working on this project?

Sure, there’s been quite a lot of technical challenges, which always arise when you try to unify a couple of implementations under a single API. An additional challenge is maintaining the project’s build, which now targets for 3 different Scala versions, Scala.JS and Scala Native. Finally, interacting with the users and the community is also demanding; you sometimes need to balance the needs of a single user or group of users with the overall usability and long-term sustainability.

5. What are the future plans for the project’s development?

At the time of writing, we are finishing work on version 2 of the library. It brings a couple of significant (and breaking!) changes, the most important being an improved way of specifying how errors should be handled in responses, and websocket support.

There are also other changes, such as unified model which will be shared with the tAPIr library. Available here.

6. What would be your advice for people willing to start their adventure with OSS?

Write something that you need yourself: this might be a wrapper for an API in your favorite language, a tooling library, a better interface to a database etc. Then of course, open-source it, but we’re not done yet! A very important step is to let the world know: write a couple of blog posts explaining why your approach is better, or what kind of problems it solves. Try promoting it on reddit or twitter. Even great libraries need some marketing to get that initial spark of interest!