hmrc / play-hal

play-hal

A HAL - Hypertext Application Language library based on Play-JSON.

This repository is a fork of HALselhof

This library is now cross compiled for Play 2.8, 2.9 and 3.0

Add the library

"uk.gov.hmrc" %% "play-hal-play-XX" % "4.X.X"

where XX is the version of Play you require

Standalone Example

// Test data which should be reflected in the resource state
case class TestData(total: Int, currency: String, status: String)

// a generated play.api.libs.json.Writes
implicit val testWrites = Json.writes[TestData]

// transfer the resource state into a full HAL resource
val data = TestData(20, "EUR", "shipped")

val resource: HalResource = data.asResource ++
  HalLink("self", "/orders") ++
  HalLink("next", "/orders?page=2") ++
  HalLink("find", "/orders{?id}", templated = true)

// transfer the resource to the Play JSON AST
val json = resource.json

Examples

Play Framework Integration

// within a Play Controller HAL resources can be serialized directly and are supported within content negotiation
import play.api.hal._
import play.api.mvc.hal._

def halOrJson = Action {
  implicit request =>
    render {
      case Accepts.Json() =>
        Ok(Json.obj("foo" -> "bar"))
      case AcceptHal() =>
        Ok(Hal.state(Json.obj("foo" -> "bar")) ++ HalLink("self", "/foo"))
    }
}

License

This code is open source software licensed under the Apache 2.0 License.

play-hal's Issues

Inconsistent JSON structure when using embedded resources

Specifying one item in the embedded Vector results in a json a structure like so:

"_embedded": {
    "kids": {
      "_links": {
        "self": {
          "href": "/people/summer"
        }
      },
      "name": "Summer",
      "age": 18
    }
}

Specifying multiple items in the embedded Vector results in a json a structure with an array like so:

  "_embedded": {
    "kids": [
      {
        "_links": {
          "self": {
            "href": "/people/morty"
          }
        },
        "name": "Morty",
        "age": 14
      },
      {
        "_links": {
          "self": {
            "href": "/people/summer"
          }
        },
        "name": "Summer",
        "age": 18
      }
    ]
  }

While this does technically respect the specification, it provides an inconsistent schema for resources with dynamic lists. Lists that can vary between 0, 1, and many resources are affected. It would be better if it was possible to specify the plurality of the embedded resource when creating it.

I haven't tested, but I imagine this issue will also apply to links.

HalLinks equality is dependent on order of links

For example, this test fails:

test("HalLinks should be equal regardless of link order") {
    Hal.links(
      HalLink("self", "/orders"),
      HalLink("ea:admin", "/admins/1")
    ) should equal(
      Hal.links(
        HalLink("ea:admin", "/admins/1"),
        HalLink("self", "/orders")
      )
    )
  }

Please clarify if the ordered nature when specifying multiple links is a conscious design decision.