To explain why you get this result in your browser when you ran the application, let's have a look at the files created by the activator new command. Under the project root directory (the shop/ directory), the build.sbt file describes your project to the build system.

It currently contains a few lines, which are as follows:

name := """shop"""

version := "1.0-SNAPSHOT"

lazy val root = project.in(file(".")).enablePlugins(PlayScala)

The first two lines set the project name and version, and the last line imports the default settings of Play projects (in the case of a Java project, this line contains PlayJava instead of PlayScala). These default settings are defined by the Play sbt plugin imported from the project/plugins.sbt file. As the development of a Play application involves several file generation tasks (templates, routes, assets and so on), the sbt plugin helps you to manage them and brings you a highly productive development environment by automatically recompiling your sources when they have changed and you hit the reload button of your web browser.

Though based on sbt, Play projects do not follow the standard sbt projects layout: source files are under the app/ directory, test files under the test/ directory, and resource files (for example, configuration files) are under the conf/ directory. For instance, the definitions of the Shop and Item types should go into the app/ directory, under a models package.

After running your Play application, try changing the source code of the application (under the app/ directory) and hit the reload button in your browser. The development HTTP server automatically recompiles and restarts your application. If your modification does not compile, you will see an error page in your browser that shows the line causing the error.

Let's have a deeper look at the files of this minimal Play application.

The app/ directory, as mentioned before, contains the application's source code. For now, it contains a controllers package with just one controller named Application. It also contains a views/ directory that contains HTML templates. We will see how to use them in Chapter 3, Turning a Web Service into a Web Application.

The conf/ directory contains two files. The conf/application.conf file contains the application configuration information as key-value pairs. It uses the Human Optimized Configuration Object Notation syntax (HOCON; it is a JSON superset, check out https://github.com/typesafehub/config/blob/master/HOCON.md for more information). You can define as many configuration points as you want in this file, but several keys are already defined by the framework to set properties, such as the language supported by the application, the URL to use to connect to a database, or to tweak the thread pools used by the application.

The conf/routes file defines the mapping between the HTTP endpoints of the application (URLs) and their corresponding actions. The syntax of this file is explained in the next section.

In our example, in the first route, the URL pattern associated with the controllers.Items.details action is /items/:id, which means that any URL starting with /items/ and then containing anything but another / will match. Furthermore, the content that is after the leading / is bound to the id identifier and is called a path parameter. The /items/42 path matches this pattern, but the /items/, /items/42/0, or even /items/42/ paths don't.

When a route contains a dynamic part such as a path parameter, the routing logic extracts the corresponding data from the URL and passes it to the action call.

You can also force a path parameter to match a given regular expression by using the following syntax:

GET     /items/$id<\d+>    controllers.Items.details(id: Long)

Here, we check whether the id path parameter matches the regular expression \d+ (at least one digit). In this case, the /items/foo URL will not match the route pattern and Play will return a 404 (Not Found) error for such a URL.

A route can contain several path parameters and each one is bound to only one path segment. Alternatively, you can define a path parameter spanning several path segments using the following syntax:

GET     /assets/*file        controllers.Assets.at(path = "/public", file)

In this case, the file identifier captures everything after the /assets/ path segment. For instance, for an incoming request with the /assets/images/favicon.png URL, file is bound to images/favicon.png. Obviously, a route can contain at most one path parameter that spans several path segments.

By default, request parameters are coerced to String values, but the type annotation id: Long (for example, in the details route) asks Play to coerce the id parameter to type Long. The routing process extracts the content corresponding to a parameter from the URL and tries to coerce it to its target type in the corresponding action (Long in our example) before calling it.

Note that /items/foo also matches the route URL pattern, but then the type coercion process fails. So, in such a case, the framework returns an HTTP response with a 400 (Bad Request) error status code.

This type coercion logic is extensible. See the API documentation of the QueryStringBindable and PathBindable classes for more information on how to support your own data types.

The parameter values of the called actions can be bound from the request URL, or alternatively, can be fixed in the routes file by using the following syntax:

GET     /          controllers.Pages.show(page = "index")
GET     /:page     controllers.Pages.show(page)

Here, in the first route, the page action parameter is set to "index" and it is bound to the URL path in the second route.

In addition to path parameters, you can also define query string parameters: parameters extracted from the URL query string.

To define a query string parameter, simply use it in the action call part of the route without defining it in the URL pattern:

GET     /items          controllers.Items.details(id: Long)

The preceding route matches URLs with the /items path and have a query string parameter id. For instance, /items and /items?foo=bar don't match but /items?id=42 matches. Note that the URL must contain at least all the parameters corresponding to the route definition (here, there is only one parameter, which is id), but they can also have additional parameters; /items?foo=bar&id=42 also matches the previous route.

Finally, you can define default values for query string parameters. If the parameter is not present in the query string, then it takes its default value. For instance, you can leverage this feature to support pagination in your list action. It can take an optional page parameter defaulting to the value 1. The syntax for default values is illustrated in the following code:

GET   /items        controllers.Items.list(page: Int ?= 1)

The preceding route matches the /items?page=42 URL and binds the page query string parameter to the value 42, but also matches the /items URL and, in this case, binds the page query string parameter to its default value 1.

Change the corresponding action definition in your code so that it takes a page parameter, as follows:

def list(page: Int) = Action { NotImplemented }

The equivalent Java code is as follows:

public static Result list(Integer page) {
  return status(NOT_IMPLEMENTED);
}

If you try to perform requests to your newly added routes from your browser, you will see a blank page. It might be interesting to try them from another HTTP client to see the full HTTP exchange between your client and your server. You can use, for example, cURL (http://curl.haxx.se/):

$ curl -v http://localhost:9000/items
> GET /items HTTP/1.1
> User-Agent: curl/7.35.0
> Host: localhost:9000
> Accept: */*
>
< HTTP/1.1 501 Not Implemented
< Content-Length: 0
<

The preceding command makes an HTTP GET request on the /items path and gets an HTTP response with the status code 501 (Not Implemented). Try requesting other paths such as /items/42, /itemss/foo, or /foo and compare the response status codes you get.

Routes are the way to expose your business logic endpoints as HTTP endpoints; your Shop service can now be used from the HTTP world!

Now that you know how to build an HTTP response containing a body, your last step to bootstrap your web service consists of returning your business data as a JSON document in the body of your HTTP responses.

Play comes with a rich library for JSON manipulation. Let's start by returning a JSON value in the details action:

import play.api.libs.json.Json

def details(id: Long) = Action {
  shop.get(id) match {
    case Some(item) =>
      Ok(Json.obj(
        "id" -> item.id,
        "name" -> item.name,
        "price" -> item.price
      ))
    case None => NotFound
  }
}

This code tries to retrieve the item in the shop and if found, returns it as a JSON object. The Json.obj function builds a JSON object from a list of name-value pairs. If there is no item with the ID passed as a parameter, the action returns a NotFound response. JSON objects have type JsValue, and Play has a built-in Writeable[JsValue] instance that sets the content type of a JSON response body to application/json.

The equivalent Java code is as follows:

import play.libs.json.Json;

public static Result details(Long id) {
  Item item = shop.get(id);
  if (item != null) {
    return ok(Json.toJson(item));
  } else {
    return notFound();
  }
}

In Java, Play uses the Jackson library (http://jackson.codehaus.org/) to automatically serialize the Item value so that you don't need to explicitly tell how to transform an Item into a JSON object. The Jackson object mapper that performs this task can handle some simple data structures like the Item class, but for more complex data structures (for example, involving cycles or bidirectional associations), you might have to supply your own serialization process by annotating your types with Jackson annotations.

The Scala API does not follow this approach because the Scala language gives convenient mechanisms that allow you to tell how to serialize data without relying on reflection and with minimal boilerplate.

If you call this action from your HTTP client, you will get a response like the following (assuming your shop has an item with the ID 42):

$ curl http://localhost:9000/items/42
{"id":42,"price":4.2,"name":"Play Framework Essentials"}

Similar to the implementation of the details action, here is how you can implement the list action and return the list of the items in the shop as a JSON array. The Java version of the code is as follows:

public static Result list() {
  return ok(Json.toJson(shop.list()));
}

Again, the Json.toJson call delegates the JSON serialization of the list of items to Jackson.

The Scala version of the code is as follows:

val list = Action {
  Ok(Json.arr(shop.list.map(item => Json.obj(
    "id" -> item.id,
    "name" -> item.name,
    "price" -> item.price
  )): _*))
}

We use the Json.arr method to create a JSON array and pass it a collection of JSON objects as a parameter.

You might have noticed that the code defining these JSON objects from the items duplicates the code already written in the details action. Instead, you should isolate the logic corresponding to the serialization of an item into a JSON object as a function and reuse it. Actually, you can do even better; the Play JSON library defines a play.api.libs.json.Writes[A] typeclass that captures the serialization logic for the type A, so you can just write an implicit value of type Writes[Item] and Play will use it when needed. This typeclass has just one method, which is writes(item: Item): JsValue that defines how to transform an Item into a JSON value. The JsValue type is an algebraic data type representing JSON values. For now, you have seen how to define JSON objects (represented by the JsObject type in Play) and arrays (JsArray), using Json.obj and Json.arr, respectively, but there are other types of JsValue such as numbers (JsNumber), strings (JsString), booleans (JsBoolean), and null (JsNull).

Your first reusable JSON serializer for items can be defined and used as follows:

import play.api.libs.json.Writes

implicit val writesItem = Writes[Item] {
  case Item(id, name, price) =>
    Json.obj(
      "id" -> id,
      "name" -> name,
      "price" -> price
    )
}

val list = Action {
  Ok(Json.toJson(shop.list))
}

def details(id: Long) = Action {
  shop.get(id) match {
    case Some(item) => Ok(Json.toJson(item))
    case None => NotFound
  }
}

The implicit value, writesItem, defines the serialization logic for Items. Then, in the list and details actions, we use Json.toJson to transform our items into JSON objects. This toJson method has the following signature:

def toJson[A](a: A)(implicit Writes[A]): JsValue

This means that it can serialize any value of type A if there is an implicit value of type Writes[A] in the implicit scope. Fortunately, Play defines such JSON serializers for common types and can combine them by chaining implicits; this is why Play is able to serialize an Item as well as a List[Item].

Though the code of your writesItem is quite concise, it follows a repetitive pattern. Each field of the Item class is serialized to a JSON field of the same name. Hopefully, Play provides a macro that generates JSON serializers following this pattern, so the previous serializer can be synthesized by just writing the following:

implicit val writesItem = Json.writes[Item]

You might be wondering why automatic generation of JSON serializers is not the default behavior. There are two reasons for this. First, the automatic generation mechanism cannot handle all data types (for example, cyclic data types). Secondly, sometimes you don't want to use the same names for your JSON object fields and your Scala object fields.

At this point, your clients can consult the items of the shop and create new items. What happens if one tries to create an item with an empty name or a negative price? Your application should not accept such requests. More precisely, it should reject them with the 400 (Bad Request) error.

To achieve this, you have to perform validation on data submitted by clients. You should implement this validation process in the business layer, but implementing it in the controller layer gives you the advantages of detecting errors earlier and error messages can directly refer to the structure of the submitted JSON data so that they can be more precise for clients.

In Java, the Jackson API provides nothing to check this kind of validation. The recommended way is to validate data after it has been transformed into a POJO. This process is described in Chapter 3, Turning a Web Service into a Web Application. In Scala, adding a validation step in our CreateItem reader requires a few modifications. Indeed, the Reads[A] data type already gives us the opportunity to report errors when the type of coercion process fails. We can also leverage this opportunity to report business validation errors. Incidentally, the Play JSON API provides combinators for common errors (such as minimum and maximum values and length verification) so that we can forbid negative prices and empty item names, as follows:

implicit val readsCreateItem = (
  (__ \ "name").read(Reads.minLength[String](1)) and
  (__ \ "price").read(Reads.min[Double](0))
)(CreateItem.apply _)

The preceding code rejects JSON objects that have an empty name or negative price. You can try it in the REPL:

scala> Json.obj("name" -> "", "price" -> -42).validate[CreateItem]
res1: play.api.libs.json.JsResult[controllers.CreateItem] = JsError(List(
    (/price,List(ValidationError(error.min,WrappedArray(0.0)))), 
    (/name,List(ValidationError(error.minLength,WrappedArray(1))))))

The returned object describes two errors: the first error is related to the price field; it has the "error.min" key and additional data, 0.0. The second error is related to the name field; it has the "error.minLength" key and an additional data, 1.

The Reads.minLength and Reads.min validators are predefined validators but you can define your own validators using the filter method of the Reads object.

Consider the following data type representing an item with an optional description:

case class Item(name: String, price: Double, description: Option[String])

In Scala, optional values are represented with the Option[A] type. In JSON, though you can perfectly represent them in a similar way, optional fields are often modeled using null to represent the absence of a value:

{ "name": "Foo", "price": 42, "description": null }

Alternatively, the absence of a value can also be represented by simply omitting the field itself:

{ "name": "Foo", "price": 42 }

If you choose to represent the absence of value using a field containing null, the corresponding Reads definition is the following:

(__ \ "name").read[String] and
(__ \ "price).read[Double] and
(__ \ "description").read(Reads.optionWithNull[String])

The optionWithNull reads combinator turns a Reads[A] into a Reads[Option[A]] by successfully mapping null to None. Note that if the description field is not present in the read JSON object, the validation fails. If you want to support field omission to represent the absence of value, then you have to use readNullable instead of read:

(__ \ "name").read[String] and
(__ \ "price).read[Double] and
(__ \ "description").readNullable[String]

This is because read requires the field to be present before invoking the corresponding validation. readNullable relaxes this constraint.

Now, consider the following recursive data type representing categories of items. Categories can have subcategories:

case class Category(name: String, subcategories: Seq[Category])

A naive Reads[Category] definition can be the following:

implicit val readsCategory: Reads[Category] = (
  (__ \ "name).read[String] and
  (__ \ "subcategories").read(Reads.seq[Category])
)(Category.apply _)

The seq combinator turns Reads[A] into Reads[Seq[A]]. The preceding code compiles fine; however, at run-time it will fail when reading a JSON object that contains subcategories:

scala> Json.obj(
  "name" -> "foo",
  "subcategories" -> Json.arr(
    Json.obj(
      "name" -> "bar",
      "subcategories" -> Json.arr()
    )
  )
).validate[Category]
java.lang.NullPointerException
        at play.api.libs.json.Json$.fromJson(Json.scala:115)
        …

What happened? Well, the seq[Category] combinatory uses the Reads[Category] instance before it has been fully defined, hence the null value and NullPointerException!

Turning implicit val readsCategory into implicit lazy val readsCategory to avoid the NullPointerException will not solve the heart of the problem; Reads[Category] will still be defined in terms of itself, leading to an infinite loop! Fortunately, this issue can be solved by using lazyRead instead of read:

implicit val readsCategory: Reads[Category] = (
  (__ \ "name).read[String] and
  (__ \ "subcategories").lazyRead(Reads.seq[Category])
)(Category.apply _)

The lazyRead combinator is exactly the same as read, but uses a byname parameter that is not evaluated until needed, thus preventing the infinite recursion in the case of recursive Reads.