The Glory of RESTNEW TOOLS TO IMPROVE REST MATURITY

Agenda Introduction

Spring HATEOAS◦ R 0.5 in May 2013, included in Spring-WebMVC 4.0

RAML◦ RESTful API Modeling Language◦ From Mulesoft

IRIS◦ Temenos Interaction, Reporting & Information Services

Introduction: REST REST: Representational State Transfer

“Architectural Styles and the Design of Network-based Software Architectures”◦ Doctorate Dissertation of Roy T, Fielding, 2000◦ “Why does the internet work so well?”

4 Interface constraints for a modern Web architecture◦ identification of resources◦ manipulation of resources through representations◦ self-descriptive messages◦ hypermedia as the engine of application state.

REST Architecture

REST Maturity Model (Leonard Richardson)

REST Maturity Spring-REST MVC enables Level 2 Maturity

◦Resource URL’s, HTTP Verbs, Status Codes◦Media type negotiation

Level 3 Maturity: Hypermedia Controls◦Documents are Self-describing

◦ Describes possible interactions via e.g. links◦HATEOAS: Hypermedia as the Engine of Application State

Spring HATEOAS

◦Provides support for generic links in Spring-RestMVC◦Hard-code URI’s◦Dynamic URI’s linking to Controllers

Basis for Spring Data REST◦Converts Data repositories directly into REST Controllers◦Links for CRUD operations

Will be included in Spring WebMVC

Spring HATEOAS Example@Controllerclass EngineController {        @RequestMapping("/engine")        HttpEntity<Resource<Order>> showOrderInProgress() {                Resource<Order> resource = Resources.wrap(order);                resource.add(linkTo(methodOn(EngineController.class).showOrdersInProgress()).withSelfRel());                resource.add(entityLinks.linkForSingleResource(order).slash(payment).withRel(payment));                return new ResponseEntity<>(orderResources, HttpStatus.OK);        }

Spring HATEOAS Example(2)@Controller@RequestMapping("/orders/{id}")@ExposesResourceFor(Payment.class)public class PaymentController {

        @RequestMapping(value = “/payment”, method = RequestMethod.PUT)        ResponseEntity<PaymentResource> submitPayment(@PathVariable("id") Order order, @RequestBody CreditCardNumber number) {                if (order == null || order.isPaid()) {                        return new ResponseEntity<PaymentResource>(HttpStatus.NOT_FOUND);                }                CreditCardPayment payment = paymentService.pay(order, number);                PaymentResource resource = new PaymentResource(order.getPrice(), payment.getCreditCard());                resource.add(entityLinks.linkToSingleResource(order));                return new ResponseEntity<PaymentResource>(resource, HttpStatus.CREATED);        }

Spring HATEOAS Conclusion Allows to create links.

Integrates in Spring REST MVC

First step to hypermedia control

RAML: RESTful API Modeling Language

Description language for RESTful API◦ Resources◦ Methods◦ Parameters◦ Responses

Both human readable and machine readable◦ YAML based◦ Focuses on description◦ Not strict: no validation, can use JSON Schema, XSD, simple example or just plain text description

Reusable resource types and traits

Design tools by MuleSoft

RAML Example #%RAML 0.8 --- title: World Music API baseUri: http://example.api.com/{version} version: v1 /songs: get: queryParameters: genre: description: filter the songs by genre /{songId}: get: body: application/json: schema: | { "$schema": "http://json-schema.org/schema", "type": "object", "description": "The canonical song representation", "properties": { "title": { "type": "string" }, "artist": { "type": "string" } } "required": [ "title", "artist" ] } delete: description: This method will *delete* an **individual song**

RAML Traits: reusable (partial) method definitions traits: - paged: queryParameters: limit: type: number skip: type: number ResourceTypes: reusable (partial) resource definitions

◦ Method API definitions◦ Nested URI’s

Schema language is not restricted◦ JSON Hyper-schema could be used, no special treatment

JSON Schema and JSON Hyper-Schema

JSON Schema: XSD for JSON◦ IETF Draft◦ Example{

"title": "Example Schema","type": "object","properties": {

"firstName": {"type": "string"},"lastName": { "type": "string"},"age": {"description": "Age in years","type": "integer","minimum": 0}

},"required": ["firstName", "lastName"]

}

JSON Hyper-Schema◦ JSON Schema + standard schema for hypermedia properties

◦ Links, schema for submission links, URI templates

IRIS Temenos Interaction, Reporting & Information Services

● Open sourced by Temenos Tech◦ ○ https://github.com/temenostech◦ ○ Origin: Dynamic Client for insurance brokers◦ ○ Forms generated by metadata

● RIM: Resource Interaction Model◦ ○ Based on HAL: Hypertext Application Language◦ ○ Links, transitions, workflow

● Full Level 3 Maturity◦ ○ Hypermedia Controls

Very little documentation

HAL: Hypertext Application Language

Links and embedded resources in JSON or XML

Separate media type: application/hal+json "_links": { "self": { "href": "/product/987" }, "upsell": [ { "href": "/product/452", "title": "Flower pot" }, { "href": "/product/832", "title": "Hover donkey" } ] }, "_embedded": { "manufacturer": { "_links": {"self": { "href": "/manufacturers/328764" } }, "name": "Manufacturer Inc.“ … }, …

Generic HAL Browser, see e.g. http://haltalk.herokuapp.com/explorer/browser.html#/

Further Reading REST Maturity Model: http://martinfowler.com/articles/richardsonMaturityModel.html

● Spring HATEOAS http://projects.spring.io/spring-hateoas/

● JSON Schema: http://json-schema.org/

● RAML: http://raml.org/

● HAL – Hypertext Application Language: http://stateless.co/hal_specification.html

● IRIS: https://github.com/temenostech/IRIS