An open-source Scala library for describing HTTP API endpoints
tapir, or Typed API descRiptions
Tapir is one of the youngest open-source libraries created by SoftwareMill-ers. We’ve asked one of the contributors — Kasper Kondzielski to tell us more about this Scala library that earned its own mascot already.
1. Could you briefly describe what does tapir library do — what problem is it trying to solve?
Tapir solves an old problem which is how to keep in sync HTTP API endpoints documentation and your code. The way it works is that it introduces another abstraction layer for describing endpoints. Later on, this description can be converted either to one of the scala http libraries or to an open-api specification. Besides that, client code can be easily derived from it by using sttp-client interpreter. Tapir enables you to describe the endpoints using pure values which results in important benefits like referential transparency. If you want to dig deeper into the technical details you can read more in this short introduction.
2. How did you or your team come up with an idea for this library?
An idea of tapir emerged once we had to generate HTTP API documentation. We weren’t able to find a solution that would meet our project’s needs. We decided to come up with a solution that would answer our needs and be programmer-friendly.
3. Why did you decide to engage in developing this open-source project?
Adam Warski told me about the tapir in the middle of December 2018. Back then I had only 1,5 months of experience in scala and it was mostly from a single commercial project. I thought that it would be a good idea to get involved in another project, especially an open-source library. It enabled me to grasp a new perspective on the Scala language, while I was still learning it. After my scala skills improved, I decided to continue my work on this project as I realized how important are the benefits that it brings to the table.
4. Is there anything specific that you learned through working on this project?
There are many things that I learned while working on tapir, mainly because I had little to no scala experience before. Just to name a few, that are most specific:
- OpenApi/Swagger — I knew about swagger and used version 2, but now I know the whole open-api specification in version 3 and I have to admit that it is very broad.
- Magnolia — it’s an amazing library for scala’s type class derivation which does the job. Without it I would, probably, be still learning shapeless library.
- Macros — Scala macros are a very powerful construct. In the beginning, they seemed similar to groovy AST transformations to me, but a deeper look into them showed me that their capabilities are way beyond that.
5. What are the future plans for the project’s development?
Apart from fixing bugs we are trying to enrich tapir with more and more integrations. If you would like to use tapir but there is a lack of an integration for a library of your choice, please let us know.
6. What would be your advice for people willing to start their adventure with OSS?
Don’t look for any excuses. The benefits that you get from contributing to open-source are just invaluable. And as my example shows, you don’t have to be an expert in a given field to contribute to a project. If you know somebody personally that is working on OSS, go and talk to them. I am sure they will be happy to help. If not, don’t worry, there are plenty of people on the internet who will be willing to share their knowledge. You just have to make this first little step 😉
Now over to you. If you want to make your first little step by contributing to tapir, just go through the list of issues and pick one!
