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.
val 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:
val eventuallyDone: Future[Unit] = increment(Increment(step = 42))
Conversely, from the server perspective implementing an HTTP endpoint is as simple as implementing a function:
increment.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: Akka-Http, Play-WS, sttp, scalaj, and XMLHttpRequest (Scala.js) ;
- servers: Akka-Http, Play, and http4s ;
- 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).
- 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 documentationor the samples.
See the Github repository.
Bestmile supports engineering work on the project.