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 ;
  • e.g. the endpoints.algebra.Urls trait defines an algebra for describing URLs.
• 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) ;
  • e.g. the endpoints.play.client.Urls trait defines a Play-based interpreter for the Urls algebra.
• compatible interpreters are in the same package ;
• e.g. the endpoints.play.client package provides interpreters that are all based on Play WS under the hood.

Algebras

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

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