endpoints4s

endpoints4s is a Scala library for remote communication. It ensures that HTTP servers, HTTP clients, and documentation always agree on the same protocol.

  • maintenance is simplified: the API documentation is automatically updated when an endpoint is modified ;
  • errors are raised at compile-time if endpoints are invoked with incompatible parameters.

Servers, clients and documentation are all derived from a single source of truth describing the underlying protocol details (e.g., which verb, path, query parameters, headers, authentication strategy, etc. to use). For instance, here is an endpoint for incrementing a counter. It uses the HTTP verb POST, the URL path /increment, a JSON request entity containing an Increment value, and it returns an empty response.

sourceval increment: Endpoint[Increment, Unit] =
  endpoint(
    post(path / "increment", jsonRequest[Increment]),
    ok(emptyResponse)
  )

From the client perspective, calling an HTTP endpoint is as simple as calling a function:

sourceval eventuallyDone: Future[Unit] = increment(Increment(step = 42)).future

Conversely, from the server perspective implementing an HTTP endpoint is as simple as implementing a function:

sourceincrement.implementedBy(inc => counter.single += inc.step)

endpoints4s takes care of constructing the HTTP requests and responses and decoding the server responses or client requests into high-level data types according to the endpoint descriptions.

In contrast with most other approaches, endpoints4s is a pure, “vanilla”, Scala library. No code generation. No macros. IDE friendly. Endpoint descriptions are first-class Scala values, which can be reused, combined, and abstracted over.

The library currently supports the following backends:

  • clients: Pekko HTTP, Akka HTTP, http4s, Play-WS, sttp, scalaj, XMLHttpRequest (Scala.js), and Fetch (Scala.js) ;
  • servers: Pekko HTTP, Akka HTTP, http4s, and Play ;
  • documentation: OpenAPI ;
  • JSON is supported via Circe, Play-Json, or ujson ;

… but the library is designed to be extensible, anyone can:

  • implement a new interpreter for the existing endpoint descriptions (e.g. generation of RAML documentation, finch client and server backend, etc.) ;
  • add new descriptions to the existing ones (e.g. to define an application-specific authentication strategy).

Getting started

  • Have a look at the quick start guide to understand in a few minutes what the library does and how to setup a project ;
  • Check out the use cases to know the typical problems that endpoints4s addresses ;
  • Browse the API documentation or the samples.

Contributing

See the Github repository.

Sponsors

Bestmile supports engineering work on the project.

1.12.1