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 ;
  • 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) ;
  • compatible interpreters are in the same package ;
  • e.g. the endpoints4s.play.client package provides interpreters that are all based on Play WS 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 Akka-HTTP server:

import endpoints4s.akkahttp.server

trait MyAkkaHttpServer extends MyCustomAlgebra
  with server.Endpoints
  with server.JsonEntitiesFromSchemas
  with server.BasicAuthentication
Warning

If you try to mix an interpreter module that doesn’t match your algebra the compiler will raise “conflicting inherited members” errors.

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
Note

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).