symantic-http
Symantic combinators for deriving clients or a server from an HTTP API
| Latest on Hackage: | 0.1.1.20190410 |
This package is not currently in any snapshots. If you're interested in using it, we recommend adding it to Stackage Nightly. Doing so will make builds more reliable, and allow stackage.org to host generated Haddocks.
An extensible, typed and embedded Domain-Specific Language (DSL) to build Web services using a write-an-API-then-derive-code-from-it approach as in servant's, but with term-level combinators instead of type-level combinators.
In this approach, writting an API can be understood like the writing of a printf's or scanf's format: such that deriving a client is like calling printf on both this format and arguments type-checking against the given format, and deriving a server is like calling scanf on both this format and handlers type-checking against the given format.
For building an HTTP client (request building and response decoding) based upon http-client, see symantic-http-client.
For building an HTTP server (request routing and response building) based upon warp, see symantic-http-server.
For streaming data (running effects (eg. in IO) during the transfer) using pipes, see symantic-http-pipes.
For learning how to use this library, you can read the demo example in symantic-http-demo.
WARNING: Be aware that this library is young (thus its interface can change without warnings and delays), has no community explicitely committed to support it (thus can die without warning), is poorly tested (thus even less ready for serious work), and — last but not least — is yours as a common for the commons (with the help of its GNU GPLv3 license).
Users of this library can be grateful to the servant's contributors whose work was helpful to have a concrete overview of the functionnalities this library could attain, and thank Oleg Kiselyov whose (once again) mind-blowing (co-)work on typed formatting was helpful to overcome the limitation of one-type-parameter symantics. Indeed the fundamental observation upon which this library is built is that one-type-parameter symantics (repr a) (aka. Tagless-Final typed DSL — basically just a clever use of type classes and instances) can be augmented with an extension type (repr (a -> k) k) extending a function to the right — while forming a category. Which makes term-level combinators able to add arguments to a function within the type they will be instantiated to (repr), such that this library's combinators (that you can extend by just writing a new type class) can be used to write an API instantiable as: a function asking arguments to generate a client's request, or a function asking handlers to generate a server's response, or some documentation type, or any other type for which you can write the type class instances required by the API combinators you use.