galeria-kaufhof / jsonhomeclient   3.0.3

Apache License 2.0 GitHub

Scala client to consume JSON home documents

Scala versions: 2.12 2.11 2.10


Build Status

No-magic Scala client to consume JSON home documents like this:

  "resources": {
    "": {
      "href": "/artists"
    "": {
	  "href-template": "/artists/{artist-id}",
      "href-vars": {
        "artist-id": ""

The json-home-client regularly loads json home documents from json home document providers, and caches them in memory. When your application retrieves some information from this json-home-client, the cached json home documents are used so that there'll be no network roundtrip.

This library uses Play's JSON library.


You must add the json-home-client to the dependencies of the build file, e.g. add to build.sbt:

libraryDependencies += "de.kaufhof" %% "json-home-client" % "3.0.3"

It is published to sonatype nexus for scala 2.11 and 2.12.


At first you setup the JsonHomeService for various hosts that provide json home documents. The first host serves a json home like the one shown above.

import de.kaufhof.jsonhomeclient._

// Specify which service/host provides which link relations
// By default, json home docs are assumed to be served from `/.well-known/home`.
val host1 = JsonHomeHost("", Seq(
  // A link relation without params
  // A link relation with template params

// Create the client, it loads the json home doc from the host
//Make sure to shutdown the ActorSystem after usage
implicit val system: ActorSystem  = ActorSystem()
implicit val materializer: ActorMaterializer  = ActorMaterializer()
val client1 = new JsonHomeClient(host1)

// Create the cache, it will regularly (using the Akka scheduler) load json home doc
// using the client. The initialTimeToWait is used for requests when the schedule did not yet
// kick in (might happen e.g. in tests) so that the json home doc was not yet requested/loaded.
// In this case the json home doc is directly loaded from the client and the cache will wait for
// the result using the given `initialTimeToWait`. Decide whether the cache
// should log output verbose or not.
val cache1 = new JsonHomeCache(
  updateInterval = 5 minutes,
  initialTimeToWait = 10 seconds,
  logVerbose = false

// The json home service, the interface for applications, set up with several json home caches
val jsonHomeService = JsonHomeService(Seq(cache1, cache2, ...))

Once the json home service is set up, you can use it to retrieve links for link-relations.

// Example 1: Get a link relation that does not expect template params
) == Some("/artists")

// Example 2: Some link relation that expects template params
  Map("artist-id" -> "acdc")
) == Some("/artists/acdc")



sbt Release


The license is Apache 2.0, see LICENSE.