This session will look at the philosophy and implementation of the new REST API. In particular, we will address why we felt a new implementation was interesting, what is and how to use a RESTful API and will look at how the new API makes integrating and extending Jahia an even simpler task than before.

1. Jahia Digital Factory
New RESTful API
Christophe Laprun / @metacosm
Jahia Solutions Group SA

2. REST?




REpresentational State Transfer
Architectural style defined by R. Fielding
Underlies the modern web
Resources identified via URIs are
manipulated via representations using a
unified interface
 Stateless
 HATEOAS (Hypermedia As The Engine Of Application State)

3. RESTful API?
 A (web service) API conforming to the REST
architecture principles
 Manipulation of entities via URIs
 Mapping of operations on data over a simple
vocabulary of HTTP methods:
 GET => read
 PUT => create or update
 POST => create or complex operations
 DELETE => delete

4. What about the existing
RESTful API?




Hybrid approach not completely RESTful
Complex
Organically grown
Implementation intertwined with rendering
pipeline

5. Goals






CRUD (Create Read Update Delete) interface to JCR nodes
Module
JSON only
Optimize for access from JS
Decouple from rendering pipeline
Implement best practices
 Respect HTTP methods semantics
 HATEOAS

6. Resources and URIs
 JCR nodes are natural matches for
resources
 Sub-resources for properties, children,
mixins and versions
 URIs should be opaque, only interesting
URI is entry point
 But:
 : => __
 [] => - -

7. Opaque URIs?
 How do we navigate the API?
 Links!
 Subset of HAL (JSON Hypertext Application Language)
 _links object recording links used to
navigate / operate / learn about
resources
 _links / <rel> / href

8. Examples
 Let’s look at node representations
 Updating a node using cURL

9. Node representation
“name" : <the node's unescaped name>,
"type" : <the node's node unescaped type name>,
"properties" : <properties representation>,
"mixins" : <mixins representation>,
"children" : <children representation>,
"versions" : <versions representation>,
"_links" : {
"self" : { "href" : “<this node’s URI>" },
"type" : { "href" : "<this node's nodetype
URI>" },
"properties" : { "href" : “<URI for this
node’s properties>" },
"mixins" : { "href" : "<URI for this node’s
mixins>" },
"children" : { "href" : "<URI for this
node’s children>" },

10. Property representation
“name" : <the property's unescaped name>,
"type" : <the property's JCR property type name>,
"multiple" : <whether this property is multivalued>,
"value" : <object or array representing the
property’s value>,
"_links" : {
"self" : { "href" : “<this node’s URI>" },
"type" : { "href" : "<this node's nodetype
URI>" },
(“target" : { "href" : “<URI of the node
being pointed at>" })*
}
*: if the property is of type PATH, REFERENCE or
WEAKREFERENCE

11. AngularJS demo application
 List sessions
 Vote for sessions and display current
rating
 Reset votes
 Show node details

12. Status
 Almost there
 Scheduled for Digital Factory (April 1st)
 Interested in your feedback
 What scenarios would you like to see made
even easier?
 Missing links?
 Versioning scheme?
 Code currently lives at:
https://github.com/metacosm/jcrestapi

13. References
 REST:
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arc
h_style.htm
 HATEOAS:
 Theory: http://roy.gbiv.com/untangled/2008/rest-apismust-be-hypertext-driven
 Simpler: http://www.slideshare.net/josdirksen/restfrom-get-to-hateoas
 HAL: http://tools.ietf.org/html/draft-kelly-json-hal-06
 AngularJS: http://angularjs.org/

14. Questions?