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.
From the client perspective, calling an HTTP endpoint is as simple as calling a function:
Conversely, from the server perspective implementing an HTTP endpoint is as simple as implementing a function:
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).
- 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.
See the Github repository.
Bestmile supports engineering work on the project.