Algebras and interpreters

In endpoints4s, 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 endpoints4s.algebra package ;
  • e.g. the `endpoints4s.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 as the algebra they implement (they can be found by looking at the “known subclasses” of an algebra, in the Scaladoc) ;
  • e.g. the `endpoints4s.http4s.client.Urls` trait defines an http4s-based interpreter for the Urls algebra.
• compatible interpreters are in the same package ;
• e.g. the `endpoints4s.http4s.client` package provides client interpreters that are all based on http4s under the hood.

Matching Algebras and Interpreters

To define endpoint descriptions you need to select which algebras you need. For instance:

import endpoints4s.algebra

trait MyCustomAlgebra extends algebra.Endpoints
  with algebra.JsonEntitiesFromSchemas
  with algebra.BasicAuthentication

Then, to interpret the endpoint descriptions you need to build an interpreter that matches this algebra. By following the aforementioned naming conventions, you should be looking for all the traits that have the same names as your algebra modules and that are in the package of the interpreter you want to use. For instance, to build an Pekko-HTTP server:

import endpoints4s.pekkohttp.server

trait MyPekkoHttpServer extends MyCustomAlgebra
  with server.Endpoints
  with server.JsonEntitiesFromSchemas
  with server.BasicAuthentication

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, Pekko HTTP, etc.) to do so. Pick the interpreters that fit your existing stack!

Family	Description
Pekko HTTP	Client and server backed by Pekko HTTP
Akka HTTP	Client and server backed by Akka HTTP
http4s	Client and server backed by http4s
Play framework	Client and server backed by Play framework
Scala.js web (Fetch)	Scala.js web client using Fetch
Scala.js web (XHR)	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