# Http Adapters
Once you have an interpreter able to execute GraphQL queries, you usually want to expose it using an HTTP API. Caliban comes with a few "ready-to-use" components (called "adapters") to expose your API with the most popular HTTP libraries.
Under the hood, adapters use the tapir (opens new window) library, so you can easily create a custom adapter with anything that tapir supports.
# Built-in adapters
Each built-in adapter comes with 3 main functions:
makeHttpServicetakes an interpreter and turns it into a route following the standard GraphQL protocol (opens new window)
makeHttpUploadServicetakes an interpreter and turns it into a route following the GraphQL multipart request protocol (opens new window)
makeWebSocketServicetakes an interpreter and turns it into a route following the GraphQL WebSocket protocol (opens new window)
Each of these functions also support a few parameters:
skipValidation(default: false) allows skipping validation when executing requests
enableIntrospection(default: true) allows disabling introspection
queryExecution(default: Parallel) defines how query optimization should work
requestInterceptor(default: empty) allows intercepting data from the request (e.g. headers) and do something with it (e.g. save it inside ZIO env)
webSocketHooks(default: empty) gives you some hooks around the WebSocket lifecycle (useful for authentication)
The following adapters are provided:
Http4sAdapterexposes a route for http4s, using circe for the Json handling.
ZHttpAdapterexposes a route for zio-http, using circe for the Json handling. This one doesn't support upload yet.
PlayHttpAdapterexposes a route for play, using play-json for the Json handling.
AkkaHttpAdapterexposes a route for akka. For historical reasons, this adapter is not fixed to any Json library, which means that you need depend on one of the tapir Json libraries and import it.
Want to use something else? Want to use one of them with a different Json library? Check the next section!
Make sure to check the examples to see the adapters in action.
# Make your own adapter
All existing adapters are actually using a common adapter under the hood, called
This adapter, available in the
caliban-tapir dependency, also have the same 3 methods
There are 2 main differences between these and the methods from the built-in adapters:
- they return one or several tapir
ServerEndpoint, which you can then pass to a tapir interpreter. The returned
RIO[R, *]as an effect type, but you can easily transform it to another effect type. A helper
convertHttpEndpointToFutureallows converting the effect type to a scala
Future(this is used in the Akka and Play interpreters).
- they require some implicit
JsonCodec, which you can get by importing the proper tapir json object
Let's say we want to use http4s but with play-json instead of circe. The built-in
Http4sAdapter uses circe so instead, we will directly use
First, we need to import 2 tapir dependencies in our project (in addition to
- a tapir interpreter for http4s:
- a tapir json codec for play-json:
import sttp.tapir.json.play._ import sttp.tapir.server.http4s.ztapir.ZHttp4sServerInterpreter val endpoints = TapirAdapter.makeHttpService(interpreter) val http4sRoute = ZHttp4sServerInterpreter().from(endpoints).toRoutes
http4sRoute is a valid http4s route ready to serve our API.
The zio-http interpreter in tapir does not include multipart and websocket support.
Caliban comes with json encoders and decoders for circe, zio-json and play-json. If you use another json library, you will need to create encoders and decoders for it (which is very simple, you can simply look at the existing ones).