pettercastro/scala-jsonapi

Scala support library for integrating the JSON API spec with Spray, Play! or Circe

Description

scala-jsonapi is a Scala library that aims to help you produce JSON output based on the JSON API specification easily and painlessly. The library is compatible with Scala version 2.11. It supports read and write for the following backends:

• Play-JSON
• Spray-JSON
• Circe

In addition, scala-jsonapi provides out-of-the-box (un)marshallers for:

• Spray and Play
• Akka Http

Current Status

This library is very much a work in progress, so expect its API to change.

Setup

To use scala-jsonapi, first add a library dependency—assuming that you have sonatype resolvers set up.

libraryDependencies += "org.zalando" %% "scala-jsonapi" % "0.6.2"

You also have to provide the used backend (e.g. spray-json).

Usage

The rich JSON API model is available via the following import:

import org.zalando.jsonapi.model._

The library provides serialization and deserialization of JSON API root objects to JSON using either Spray-JSON or Play-JSON. Please note that you need to explicitly add a dependency to either spray-json or play-json to your project.

Spray-JSON

import org.zalando.jsonapi.json.sprayjson.SprayJsonJsonapiProtocol._
import spray.json._

// Serialization
val rootObject: RootObject = ???
rootObject.toJson

// Deserialization
val json: JsValue = ???
json.convertTo[RootObject]

Play-JSON

Along with adding the scala-jsonapi library dependency, also include spray-httpx for marshalling support

libraryDependencies += "io.spray" %% "spray-httpx" % "1.3.3"

The JSON API support can then be imported using PlayJsonJsonapiSupport as follows

import org.zalando.jsonapi.json.playjson.PlayJsonJsonapiSupport._
import play.api.libs.json._

// Serialization
val rootObject: RootObject = ???
Json.toJson(rootObject)

// Deserialization
val json: JsValue = ???
Json.fromJson[RootObject](json)

Creating a JSON API Root Object

scala-jsonapi provides type class JsonapiRootObjectWriter so that you can create a JSON API representation for your resources. The following code snippet demonstrates its usage:

import org.zalando.jsonapi
import jsonapi.Jsonapi

case class Person(name: String)

implicit val personJsonapiWriter = new JsonapiRootObjectWriter[Person] {
  override def toJsonapi(person: Person) = {
    ???
  }
}

val personRootObject: RootObject = Jsonapi.asJsonapi(Person("Boris M."))

In contrast there is a type class called JsonapiRootObjectReader that supports conversion from JSON API representation to your resources. To illustrate:

import org.zalando.jsonapi
import jsonapi.Jsonapi

case class Person(name: String)

implicit val personJsonapiReader = new JsonapiRootObjectReader[Person] {
  override def fromJsonapi(rootObject: RootObject) = {
    ???
  }
}

val person: Person = Jsonapi.fromJsonapi[Person](RootObject(...))

For complete usage, see the specs example.

JSON API Links Support

There is support for string and object links.

To create a string "self" link:

Links.self("href", None)

To create an object "self" link:

Links.self("href", Some(meta))

Publishing and Releasing

Publishing and releasing is made with help of the sbt-sonatype plugin.

License

scala-jsonapi is licensed under the MIT license unless otherwise stated in the license files in higher directories (if any).