Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pheymann/typedapi
Build your web API on the type level.
https://github.com/pheymann/typedapi
api scala servant shapeless typelevel typesafe
Last synced: 2 months ago
JSON representation
Build your web API on the type level.
- Host: GitHub
- URL: https://github.com/pheymann/typedapi
- Owner: pheymann
- License: mit
- Created: 2018-02-27T16:43:21.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2019-05-22T09:41:25.000Z (over 5 years ago)
- Last Synced: 2024-09-27T21:05:22.934Z (4 months ago)
- Topics: api, scala, servant, shapeless, typelevel, typesafe
- Language: Scala
- Homepage:
- Size: 427 KB
- Stars: 161
- Watchers: 15
- Forks: 10
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/pheymann/typedapi)
[](https://maven-badges.herokuapp.com/maven-central/com.github.pheymann/typedapi-shared_2.12)
[](https://gitter.im/pheymann/Lobby)
[](https://www.scala-js.org/)
*experimental project*: see issues [#39](https://github.com/pheymann/typedapi/issues/39) and [#41](https://github.com/pheymann/typedapi/issues/41)
# Typedapi
Define type safe APIs and let the Scala compiler do the rest:
### Api definition
```Scala
import typedapi._
val MyApi =
// GET {body: User} /fetch/user?{name: String}
api(method = Get[MT.`application/json`, User],
path = Root / "fetch" / "user",
queries = Queries add Query[String]('name)) :|:
// POST {body: User} /create/user
apiWithBody(method = Post[MT.`application/json`, User],
body = ReqBody[Json, User],
path = Root / "create" / "user")
```
And for the Servant lovers:
```Scala
import typedapi.dsl._
val MyApi =
// GET {body: User} /fetch/user?{name: String}
(:= :> "fetch" :> "user" :> Query[String]('name) :> Get[MT.`application/json`, User]) :|:
// POST {body: User} /create/user
(:= :> "create" :> "user" :> ReqBody[Json, User] :> Post[MT.`application/json`, User])
```
### Client side
```Scala
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
```Scala
import typedapi.server._
val fetch: String => IO[Result[User]] = name => findUserIO(name).map(success)
val create: User => IO[Result[User]] = user => createUserIO(user).map(success)
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](https://github.com/pheymann/typedapi/tree/master/docs/example).
## 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](https://github.com/haskell-servant/servant) and it provides an API layer which is independent of the underlying server/client implementation. Right now Typedapi supports:
- [http4s](https://github.com/http4s/http4s)
- [akka-http](https://github.com/akka/akka-http)
- [scalaj-http](https://github.com/scalaj/scalaj-http) on the client-side
- ScalaJS on the client-side
If you need something else take a look at this [doc](https://github.com/pheymann/typedapi/blob/master/docs/ExtendIt.md#write-your-own-client-backend).
## 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" %
"com.github.pheymann" %% "typedapi-server" %
// http4s support
"com.github.pheymann" %% "typedapi-http4s-client" %
"com.github.pheymann" %% "typedapi-http4s-server" %
// akka-http support
"com.github.pheymann" %% "typedapi-akka-http-client" %
"com.github.pheymann" %% "typedapi-akka-http-server" %
// Scalaj-Http client support
"com.github.pheymann" %% "typedapi-scalaj-http-client" %
// ScalaJS client support
"com.github.pheymann" %% "typedapi-js-client" %
```
You can also build it on your machine:
```
git clone https://github.com/pheymann/typedapi.git
cd typedapi
sbt "+ publishLocal"
```
## Ammonite
Typedapi also offers an improved experience for [Ammonite](http://ammonite.io/#Ammonite-REPL) and [ScalaScripts](http://ammonite.io/#ScalaScripts):
```Scala
import $ivy.`com.github.pheymann::typedapi-ammonite-client:`
import typedapi._
import client._
import amm._
val Readme = api(Get[MT.`text/html`, String], Root / "pheymann" / "typedapi" / "master" / "README.md")
val readme = derive(Readme)
// gives you the raw scalaj-http response
val cm = clientManager("https://raw.githubusercontent.com")
val response = get().run[Id].raw(cm)
response.body
response.headers
...
```
In case Ammonite cannot resolve `com.dwijnand:sbt-compat:1.0.0`, follow [this](https://github.com/pheymann/typedapi/blob/master/docs/ClientCreation.md#ammonite) solution.
## Documentation
The documentation is located in [docs](https://github.com/pheymann/typedapi/blob/master/docs) and covers the following topics so far:
- [How to define an API](https://github.com/pheymann/typedapi/blob/master/docs/ApiDefinition.md)
- [How to create a client](https://github.com/pheymann/typedapi/blob/master/docs/ClientCreation.md)
- [How to create a server](https://github.com/pheymann/typedapi/blob/master/docs/ServerCreation.md)
- [Extend the library](https://github.com/pheymann/typedapi/blob/master/docs/ExtendIt.md)
- Typelevel Summit 2018 Berlin Talk [Typedapi: Define your API on the type-level](https://github.com/pheymann/typelevel-summit-2018)
- and a [post](https://typelevel.org/blog/2018/06/15/typedapi.html) on the Typelevel Blog describing the basic concept behind this library.
## Dependencies
- [shapeless 2.3.3](https://github.com/milessabin/shapeless/)
## 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.