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.