pheymann / typedapi

Build your web API on the type level.

GitHub

Build Status Maven Central Gitter Scala.js

Stable Version: 0.1.0, Current Development: branch 0.2.0-release

Typedapi

Define type safe APIs and let the Scala compiler do the rest:

Api definition

For the Servant lovers:

import typedapi.dsl._

val MyApi = 
  // GET {body: User} /fetch/user?{name: String}
  (:= :> "fetch" :> "user" :> Query[String]('name) :> Get[Json, User]) :|:
  // POST {body: User} /create/user
  (:= :> "create" :> "user" :> ReqBody[Json, User] :> Post[Json, User])

And for all the others:

import typedapi._

val MyApi =
  // GET {body: User} /fetch/user?{name: String}
  api(method = Get[Json, User], path = Root / "fetch" / "user", queries = Queries add Query[String]('name)) :|:
  // POST {body: User} /create/user
  apiWithBody(method = Post[Json, User], body = ReqBody[Json, User], path = Root / "create" / "user")

Client side

import typedapi.client._

val (fetch, create) = deriveAll(MyApi)

import typedapi.client.http4s._; import cats.effect.IO; import org.http4s.client.blaze.Http1Client

val cm = ClientManager(Http1Client[IO]().unsafeRunSync, "http://my-host", 8080)

fetch("joe").run[IO](cm): IO[User]

Server side

import typedapi.server._

val fetch: String => IO[User] = name => ???
val create: User => IO[User] = user => ???

val endpoints = deriveAll[IO](MyApi).from(fetch, create)

import typedapi.server.http4s._; import cats.effect.IO; import org.http4s.server.blaze.BlazeBuilder

val sm     = ServerManager(BlazeBuilder[IO], "http://my-host", 8080)
val server = mount(sm, endpoints)

server.unsafeRunSync()

This is all you have to do to define an API with multiple endpoints and to create a working client and server for them.

You can find the above code as a complete project here.

Motivation

This library is the result of the following questions:

How much can we encode on the type level? Are we able to describe a whole API and generate the call functions from that without using Macros?

It is inspired by Servant and it provides an API layer which is independent of the underlying server/client implementation. Right now Typedapi supports:

If you need something else take a look at this doc.

Get this library

It is available for Scala 2.11, 2.12 and ScalaJS and can be downloaded as Maven artifact:

// dsl
"com.github.pheymann" %% "typedapi-client" % <version>
"com.github.pheymann" %% "typedapi-server" % <version>

// http4s support
"com.github.pheymann" %% "typedapi-http4s-client" % <version>
"com.github.pheymann" %% "typedapi-http4s-server" % <version>

// akka-http support
"com.github.pheymann" %% "typedapi-akka-http-client" % <version>
"com.github.pheymann" %% "typedapi-akka-http-server" % <version>

// Scalaj-Http client support
"com.github.pheymann" %% "typedapi-scalaj-http-client" % <version>

// ScalaJS client support
"com.github.pheymann" %% "typedapi-js-client" % <version>

You can also build it on your machine:

git clone https://github.com/pheymann/typedapi.git
cd typedapi
sbt "+ publishLocal"

Documentation

The documentation is located in docs and covers the following topics so far:

Dependencies

Contribution

Contributions are highly appreciated. If you find a bug or you are missing the support for a specific client/server library consider opening a PR with your solution.