In the previous sections, we extracted specific fields from the JSON response using Scala extractors. We can do one better and extract full case classes.

When moving beyond the REPL, programming best practice dictates that we move from json4s types to Scala objects as soon as possible rather than passing json4s types around the program. Converting from json4s types to Scala types (or case classes representing domain objects) is good practice because:

Json4s lets us extract case classes directly from JObject instances, making writing the layer converting JObject instances to custom types easy.

Let's define a case class representing a GitHub user:

scala> case class User(id:Long, login:String)
defined class User

To extract a case class from a JObject, we must first define an implicit Formats value that defines how simple types should be serialized and deserialized. We will use the default DefaultFormats provided with json4s:

scala> implicit val formats = DefaultFormats
formats: DefaultFormats.type = DefaultFormats$@750e685a

We can now extract instances of User. Let's do this for Martin Odersky:

scala> val url = "https://api.github.com/users/odersky"
url: String = https://api.github.com/users/odersky

scala> val jsonResponse = parse(Source.fromURL(url).mkString)
jsonResponse: JValue = JObject(List((login,JString(odersky)), ...

scala> jsonResponse.extract[User]
User = User(795990,odersky)

This works as long as the object is well-formatted. The extract method looks for fields in the JObject that match the attributes of User. In this case, extract will note that the JObject contains the "login": "odersky" field and that JString("odersky") can be converted to a Scala string, so it binds "odersky" to the login attribute in User.

What if the attribute names differ from the field names in the JSON object? We must first transform the object to have the correct fields. For instance, let's rename the login attribute to userName in our User class:

scala> case class User(id:Long, userName:String)
defined class User

If we try to use extract[User] on jsonResponse, we will get a mapping error because the deserializer is missing a login field in the response. We can fix this using the transformField method on jsonResponse to rename the login field:

scala> jsonResponse.transformField { 
  case("login", n) => "userName" -> n 
}.extract[User]
User = User(795990,odersky)

What about optional fields? Let's assume that the JSON object returned by the GitHub API does not always contain the login field. We could symbolize this in our object model by giving the login parameter the type Option[String] rather than String:

scala> case class User(id:Long, login:Option[String])
defined class User

This works just as you would expect. When the response contains a non-null login field, calling extract[User] will deserialize it to Some(value), and when it's missing or JNull, it will produce None:

scala> jsonResponse.extract[User]
User = User(795990,Some(odersky))

scala> jsonResponse.removeField { 
  case(k, _) => k == "login" // remove the "login" field
}.extract[User]
User = User(795990,None)

Let's wrap this up in a small program. The program will take a single command-line argument, the user's login name, extract a User instance, and print it to screen:

// GitHubUser.scala

import scala.io._
import org.json4s._
import org.json4s.native.JsonMethods._

object GitHubUser {

  implicit val formats = DefaultFormats

  case class User(id:Long, userName:String)

  /** Query the GitHub API corresponding to `url` 
    * and convert the response to a User.
    */
  def fetchUserFromUrl(url:String):User = {
    val response = Source.fromURL(url).mkString
    val jsonResponse = parse(response)
    extractUser(jsonResponse)
  }

  /** Helper method for transforming the response to a User */
  def extractUser(obj:JValue):User = {
    val transformedObject = obj.transformField {
      case ("login", name) => ("userName", name)
    }
    transformedObject.extract[User]
  }

  def main(args:Array[String]) {
    // Extract username from argument list
    val name = args.headOption.getOrElse { 
      throw new IllegalArgumentException(
        "Missing command line argument for user.")
    }
    
    val user = fetchUserFromUrl(
      s"https://api.github.com/users/$name")

    println(s"** Extracted for $name:")
    println()
    println(user)

  }

}

We can run this from an SBT console as follows:

$ sbt
> runMain GitHubUser pbugnion
** Extracted for pbugnion:
User(1392879,pbugnion)