Rescator is a very simple Scala Json Rest Client API

ALPHA version which can already be tested but the API can still evolve so don’t rely on it i in a closed way…

For the time being, Rescator is 100% Scala and is aimed at:

• Calling Rest Json API in a very simple way
• Mapping received Json data to tuples using XPath-like syntax
• No (too) weird operators

Rescator wraps the great Scala dispatch library which is really powerful and designed in a fantastic way but quite cryptic to use IMHO. Not being a Scala guru yet and loving clear code, I must admit that dispatch relies too much on those weird operators (>~, >#, >-, >:>…) mixed with extreme functional syntax. It makes very concise code but quite difficult to read and to write for the basic developer.
I love Scala in a whole but richness of an API relies not only on its intrinsic power but also on its simplicity of usage. Scala versatile syntax allows to provide simplicity so why not create simple APIs completely hiding its complex guts?
My aim is this one and even if I don’t succeed, I’ll try…

Here is a sample working code with this very draft code:

Mapping Json to tuples

Building a dispatch JsValue from a string

import org.mandubian.rescator._
val js = JS(""" 
	{"child1" : {"child11" : {"child112" : "blabla"}}, 
	"child2" : {"child21" : 12345, "child22" : ["alpha", "beta", "delta"]}} 
""")

js: dispatch.json.JsValue = {"child1" : {"child11" : {"child112" : "blabla"}}, "child2" : {"child21" : 12345, "child22" : ["alpha", "beta", "delta"]}}

Mapping a dispatch JsValue to a tuple

import org.mandubian.rescator._

val (child1, child112, child21, child22) = js >>>
	(	
	  R\'child1 as obj, 
	  R\'child1\'child11\'child112 as str,
	  R\'child2\'child21 as int,
	  R\'child2\'child22 as list
	)

shall return:
		
child1: Option[dispatch.json.JsObject] = Some({"child11" : {"child112" : "blabla"}})
child112: Option[String] = Some(blabla)
child21: Option[Int] = Some(12345)
child22: Option[List[dispatch.json.JsValue]] = Some(List("alpha", "beta", "delta"))

Please remark:

• The R\ which can be written ROOT\ means it begins from the ROOT node. If you remove the R\, it works also as it will start on ROOT node by default. So you can write also:

	
	val (child1, child112, child21, child22) = js >>>
		(	
		  'child1 as obj, 
		  'child1\'child11\'child112 as str,
		  'child2\'child21 as int,
		  'child2\'child22 as list
		)

• XPath based on symbols ‘parent\’child to get child node in JSON { parent : { child : "blabla" } }

why \ instead of / ? because // XPath expression will be added and // is a comment in Scala and Scala-XML also uses \

• as to tell the tuple mapper what is the expected type. Here are the accepted extractors coming:
  • str for a string
  • bool for a boolean
  • num for a number (parses a bigdecimal as json std requires
  • int, long, float, double, short for different number types you require
  • list for an array
  • obj for getting a complete dispatch.json.JsObject and manage it yourself

• the result is a TupleN[Option[T]] so it means, if you give a bad JsonPath, rescator shall put None in the tuple

Mapping to a tuple with not found JsonPath or bad type

import org.mandubian.rescator._

val (child1, child112, child21, child22) = js >>>
	(	
	  'child1 as obj, 
	  'child1\'child11\'child112 as list,
	  'child2\'child21 as str,
	  'child2\'child3 as num
	)

shall return

child1: Option[dispatch.json.JsObject] = Some({"child11" : {"child112" : "blabla"}})
child112: Option[List[dispatch.json.JsValue]] = None
child21: Option[String] = Some(12345)
child22: Option[BigDecimal] = None

Please remark:

• None is returned when:
  • the JsonPath is not found in the JsValue
  • the mapping type is not the right one

Calling/mapping a GET Json API

import org.mandubian.rescator._

val (query_obj, query_type, trim_place) = 
	GET("https://api.twitter.com/1/geo/search.json?query=Twitter%20HQ") >>> 
		(	
			'query as obj, 
			'query\'type as str, 
			'query\'params\'trim_place as bool
		)

Please remark:

• GET to call an URL in GET mode (POST should come soon)
• >>> is quite easy to understand

Here we are for the time being but more coming soon!

Have fun and don’t hesitate to give ideas and contribute!