Using types to describe an API

Why did we pick the tapir library?

The basics

Tapir schema for Translation

Tapir schema for Product

Tapir schema for NonEmptySet from Cats

Using types to describe an API

Describing your API using types is not bleeding edge academic research stuff like you might have guessed. There are several libraries existing for it!

Some of these are endpoints, rho included in http4s, and tapir. We will be using tapir in our implementation.

Why did we pick the tapir library?

We wanted to use something that allows us to generate a http4s server. This already narrowed down the options a bit.

It should be able to generate API documentation, which nowadays means Swagger/OpenAPI support.

It should support not only http4s but more options as well.

Tapir meets all our requirements. The library is still pretty young and may be subject to breaking changes, so please keep this in mind when reading through the following part.

The basics

The tapir library assumes that you describe your API using the Endpoint type, which is more concretely defined as follows: Endpoint[I, E, O, S].

• The type I defines the input given into the endpoint.

• Type type E defines the error (or errors) that may be returned by the endpoint.

• The type O defines the possible output of the endpoint.

• The type S specifies the type of streams that are used for input and output.

An endpoint can have attributes like name or description, which will be used in the generated documentation. You can also map input and output parameters into case classes.

Please note that all mappings have to be bidirectional because tapir must be able to generate server and client code from it.

Regarding the encoding and decoding of data, we will need our Circe codecs and additionally some schema definitions required by tapir. In concrete, we will need to define implicit SchemaFor[T] instances for each of our models.

Tapir schema for Translation

We will start with the Translation model.