Introducing: REST and JSON in Caché - InterSystems Benelux

Introducing: REST
and JSON in Caché
Olivier Caudron
Senior Sales Engineer
InterSystems Benelux

What is REST?
• REST ("Representational State Transfer") is
NOT a technology or "standard"
• REST is a series of patterns, a set of principles,
using the existing services of HTTP to express
client queries to a server
• It is a reaction to the complexity of RPC
protocols like SOAP that defer functionalities to
a higher layer (mostly in the SOAP "envelope")
• http://en.wikipedia.org/wiki/
Representational_state_transfer

Typical RESTFul Patterns
• Use the HTTP "verbs" for CRUD operations:
• HTTP POST == CREATE record(s)
• HTTP GET == READ record(s)
• HTTP PUT == UPDATE record(s)
• HTTP DELETE == DELETE record(s)
• Use the URL for identifying resources
• E.g. GET http://localhost/restapp/employee/1
• The structure of the URL is not standardized in REST;
it might also be:
http://localthost/restapp?resource=employee&id=1
or some other variant.

Uses of REST
• REST is mainly an architecture style for web
*applications* (not relevant for *static* websites)
• Can use REST as an alternative for SOAP/WS:
• "RESTFul web services"
• JUST an architecture style: NOTHING is standardized!!!
• Object serialization is NOT defined (often use JSON)
• Parameter passing is NOT standardized
• Security is NOT defined in REST
• Transaction handling, etc… ?
• As long as it's not better standardized, not suitable
for WS interoperability IMHO

What is JSON?
• JSON ("JavaScript Object Notation") is an
object serialization system based on the
JavaScript syntax
• !!! Albeit very close, JSON's notation is NOT identical
to the JS syntax, there are significant differences !!!
• However the contract is that the JS "eval" command
will be able to deserialize any JSON stream
• JSON's specification is very short (a onepager)
and easy to understand
• See http://www.ietf.org/rfc/rfc4627.txt or
http://www.json.org/

JSON in a Nutshell
• 2 base containers: object and array
• Array: [1,"foo","bar",3.141592]
• Object: {foo:"bar",val:10}
• Can be nested: arrays may contain objects or arrays,
and vice-versa, down several levels
• Datatypes: object, array, string, number, boolean
(true, false), null
• Unlike JS, strings can only be enclosed in double quotes
• Strings are unicode only
• Character escape rules limited compared to JS

Uses for JSON
• Originally, used to (de)serialize JS structures
• Now used in interoperability contexts where
JSON is used between diverse OO systems
• E.g. Javascript and PHP
• JSON reflects the fact that JS is a prototypebased
OO language, not a class-based OO
language like Java, C++, Caché…
• No metadata (classes), structures are completely
dynamic need to define conventions between
communicants on how to use the data!

Why JSON?
• JSON is becoming increasingly popular
• May eventually completely replace XML (AJAX) for
browser/server communications
• MUCH simpler than XML (or others like EDI)
• More human-readable than XML (most of the time)
• MUCH more efficient to parse and serialize
• Much more size-efficient than XML (but not EDI)
• Better integration with Javascript

Downsides of JSON
• XML has many advantages over JSON:
• Semantics & validation (DTD, XSD, WSDL, Schematron…)
• Clear support for encoding (lacking in JSON –
completely relies on convention)
• Integration with RPC protocols (SOAP & WS)
• Integration with security protocols beyond point-to-point
(WS-Security, WS-Policy) and other services
(WS-Transaction etc.)
• IMHO, JSON wins hands down in the browser
context but XML wins hands down in the web
services context!

3 rd Party Support
• The increasing popularity of JSON makes that
it is very well supported by all sorts of tools:
• HTML frameworks: JQuery, AngularJS, etc.
• Server-side products: PHP and others, even
databases
• Some frameworks rely entirely on JSON and
provide a completely transparent
serialization/deserialization (AngularJS)

Why REST and JSON in one Presentation?
• REST is unrelated to JSON but requires some
serialization technique for any serious work
(could be XML)
• JSON is unrelated to REST but needs some
interoperability technique (transport)
• Nowadays, most REST projects use JSON as
serialization mechanism
• On the other hand, JSON is used a lot outside of
the REST context (e.g. replacement for AJAX)

REST in Caché
• RESTFul patterns can be used in any version
of Caché using CSP (with some work)
• …with the exception of some RESTFul URLs
e.g. http://myserver/myapp/resource/id
• To support those URLs, a change in the CSP
application definition was required
• Will be available in 2013.2, already stable
• Further, we implemented an elegant
dispatching mechanism for RESTFul requests
• Note that REST is irrelevant to ZEN

Using REST in Caché 2013.2
• Typically, you will create a second (or more)
CSP application for a given namespace
• Primary CSP application used to serve static and non-
RESTFul pages
• On this application, define
a "dispatch class"
• New setting
• CSP file settings and custom
pages disabled: not relevant
to RESTFul operations

Using REST in Caché 2013.2
• The dispatch class is a class that inherits from
%CSP.REST and defines an xdata block UrlMap
• Routes RESTFul URLs to classmethods
• (REST is a stateless API: no instance methods)
• Declare the HTTP verb
• Can pass parameters by prefixing them with a colon

REST in Ensemble
• A support exists in Ensemble for RESTFul
communications (services and operations)
• See the EnsLib.REST package or the
Demo.REST package in the EnsDemo
namespace

JSON in ZEN
• Because of JSON's efficiency and practicality,
it is increasingly used in ZEN
• Javascript notations are also increasingly used to
define contents or structure for components (e.g.
navigator, finderPane…)
• To feed a JSON-aware component, use one
of the json providers: jsonProvider,
jsonSQLProvider or jsonArrayProvider
• Invisible component added to the ZEN page definition
• Link via ControllerId attribute of component

JSON in CSP
• In Caché 2013.1, JSON serialization/deserialization
methods have been made public and can be used
outside of ZEN
• Can be an alternative to #SERVER()# and
#CALL()# in CSP, possibly with REST (2013.2)
• JSON is not as well-integrated to CSP as hyperevents
• …but can be interesting to use with JSON-enabled 3 rd
party frameworks (e.g. JQuery, AngularJS)
• Could possibly be used in other contexts, e.g. to
communicate between PHP and Caché

DEMO

Introducing: REST
and JSON in Caché
Olivier Caudron
Senior Sales Engineer
InterSystems Benelux