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:
In addition, scala-jsonapi provides out-of-the-box (un)marshallers for:
- Spray and Play
- Akka Http
This library is very much a work in progress, so expect its API to change.
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).
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.
import org.zalando.jsonapi.json.sprayjson.SprayJsonJsonapiProtocol._
import spray.json._
// Serialization
val rootObject: RootObject = ???
rootObject.toJson
// Deserialization
val json: JsValue = ???
json.convertTo[RootObject]
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)
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.
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 is made with help of the sbt-sonatype plugin.
scala-jsonapi is licensed under the MIT license unless otherwise stated in the license files in higher directories (if any).