Algebras and interpreters

In endpoints, we call “algebra interfaces” (or just algebras) the traits that provide methods for constructing and combining descriptions of endpoints. You can find more details about the design of these algebras in the Design in a nutshell page.

The concepts defined by algebras are given a concrete meaning by interpreters. In practice, we have three kinds of interpreters:

  • clients building requests (their URL, headers and entity) and decoding responses,
  • servers decoding requests and building responses,
  • documentation in a machine-readable format.

Naming conventions

  • algebras are defined as traits in the endpoints.algebra package ;
  • algebras’ dependencies can be found in their super types ;
  • interpreters are traits that have the same name of the corresponding algebra (they can also be found by looking at the “known subclasses” of an algebra, in the Scaladoc) ;
  • compatible interpreters are in the same package ;
  • e.g. the package provides interpreters that are all based on Play WS under the hood.


Algebras form a hierarchy: it is possible to extend an algebra with additional vocabulary, or to mix several algebras together to merge their vocabulary. This hierarchy can be seen in the diagram generated by the API documentation.

The following table lists the available algebras and points to their documentation. You should start by reading the documentation of the Endpoints algebra, and the documentation of the JsonEntities and JsonSchemas algebras if you want to work with JSON.

Name Description
Endpoints HTTP endpoints
JsonEntities JSON request and response entities
JsonSchemas JSON schemas of data types
ChunkedEntities Streamed requests and responses
Assets Asset segments, endpoints serving fingerprinted assets
MuxEndpoints Multiplexed HTTP endpoints


Interpreters give a concrete meaning to the vocabulary and operations provided by the algebras. They usually rely on other libraries (e.g. circe, Akka HTTP, etc.) to do so. Pick the interpreters that fit your existing stack!

Family Description
Akka HTTP Client and server backed by Akka HTTP
Play framework Client and server backed by Play framework
http4s Server backed by http4s
Scala.js web Scala.js web client using XMLHttpRequest
scalaj-http JVM client backed by scalaj-http
sttp JVM client backed by sttp
OpenAPI Generates OpenAPI documents for endpoints definitions
circe Builds circe codecs out of JSON schema definitions
Play JSON Builds Play JSON Reads and Writes out of JSON schema definitions

You can have different stacks on the client-side and the server-side. For instance, you can have a server backed by Play framework, a client backed by Akka HTTP, and another client backed by Scala.js (for web browsers).