endpoints 0.13.0

endpoints

endpoints 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))
CounterEndpoints.scala

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

val eventuallyDone: Future[Unit] = increment(Increment(step = 42))
CounterClientFuture.scala

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

increment.implementedBy(inc => counter.single += inc.step)
CounterServer.scala

The endpoints library 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, endpoints 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 and Play ;
  • documentation: OpenAPI document ;
  • JSON is supported via Circe or Play-Json ;

… 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, http4s 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 endpoints addresses ;
  • Browse the API documentation or the samples ;
  • Get in touch in the gitter room.

Contributing

See the Github repository.

Sponsors

Bestmile supports engineering work on the project.