JSON:API v1.1 implementation in scala

Features

Automatic generation of jsonapi json writers with relationship handling for case classes

Requirements

Tested to work on Scala 2.12.10 or 2.13.3
If you are using Scala 2.12 use the macro paradise plugin. Add addCompilerPlugin("org.scalamacros" % "paradise" % "2.1.0" cross CrossVersion.full) into your build.sbt somewhere.
If you are using Scala 2.13 you should instead use the compiler flag -Ymacro-annotations.
An example for handling cross-compiling with both can be found in project/MacrosCompiler.

Releasing

Releasing is done automatically using sbt-ci-release.

Example

import _root_.spray.json.DefaultJsonProtocol._
import com.qvantel.jsonapi._

implicit val apiRoot: ApiRoot = ApiRoot(None)

@jsonApiResource final case class Employee(id: String, name: String)
@jsonApiResource final case class Company(id: String, name: String, employees: ToMany[Employee])

val acme = Company("1", "acme", ToMany.loaded(Seq(Employee("1", "number one 1"))))

val json = rawOne(acme)
val parsed = readOne[Company](json, Set("employees"))

acme == parsed // true

or see https://github.com/Doikor/jsonapi-scala-example

Known issues

loop handing on reader side (relationship path has to be given manually)

JsonApiClient

There is a very generic JsonApiClient interface for implementing a simple client interface for handling the http query writing side of this

The subproject "pekko-client" has an implementation of this using pekko-http

The subproject "http4s-client" has an implementation of this using http4s

Usage

import cats.data.OptionT
import com.qvantel.jsonapi.JsonApiClient

val jac = JsonApiClient.instance // won't work if you don't have an actual implementations stuff in scope. See setup.

val one: IO[Option[BillingAccount]] = jac.one[BillingAccount]("ba1") 
val many: IO[List[BillingAccount]] = jac.many[BillingAccount](Set("ba1", "ba2"))

// can also load includes at the same time
val withIncludes = jac.one[BillingAccount]("ba1", Set("customer-account"))

// includes can also be loaded on their own with a method
val ba: OptionT[IO, BillingAccount]  = OptionT(jac.one[BillingAccount]("ba"))
val ca: OptionT[IO, CustomerAccount] = ba.semiflatMap(_.customerAccount.load)

// filtering support
val filtered = jac.filter[BillingAccount]("some nice filter string here")

Setup

pekko-http client

// needs ActorSystem and Materializer for pekko-http
// the ApiEndPoint is used to as the "root" where to launch queries
import io.lemonlabs.uri.typesafe.dsl._
import org.apache.pekko.actor.ActorSystem
import org.apache.pekko.stream.Materializer
import com.qvantel.jsonapi.ApiEndpoint
import com.qvantel.jsonapi.JsonApiClient
import com.qvantel.jsonapi.client.pekko.PekkoClient._

implicit val system: ActorSystem  = ActorSystem()
implicit val materializer: Materializer     = Materializer(system)
implicit val endpoint: ApiEndpoint = ApiEndpoint.Static("http://localhost:8080/api")

val jac = JsonApiClient.instance

akka-http client (to be deprecated in favor of pekko-http)

// needs ActorSystem and Materializer for akka-http
// the ApiEndPoint is used to as the "root" where to launch queries
import io.lemonlabs.uri.typesafe.dsl._
import akka.actor.ActorSystem
import akka.stream.ActorMaterializer
import com.qvantel.jsonapi.ApiEndpoint
import com.qvantel.jsonapi.JsonApiClient
import com.qvantel.jsonapi.client.akka.AkkaClient._

implicit val system: ActorSystem  = ActorSystem()
implicit val materializer: ActorMaterializer = ActorMaterializer()
implicit val endpoint: ApiEndpoint = ApiEndpoint.Static("http://localhost:8080/api")

val jac = JsonApiClient.instance

http4s client

Setup for http4s client

import io.lemonlabs.uri.typesafe.dsl._
import org.http4s.client.Client
import org.http4s.client.blaze.Http1Client
import cats.effect.IO
import com.qvantel.jsonapi.ApiEndpoint
import com.qvantel.jsonapi.JsonApiClient

import com.qvantel.jsonapi.client.http4s.Http4sClient._
import com.qvantel.jsonapi.client.http4s.JsonApiInstances._


implicit val endpoint: ApiEndpoint = ApiEndpoint.Static("http://localhost:8080/api")

implicit val client: Client[IO] = Http1Client[IO]().unsafeRunSync()

val jac = JsonApiClient.instance

qvantel / jsonapi-scala 11.0.2