-Introduction to REST and REST Maturity -Spring HATEOAS -RAML: RESTful API Modeling Language -IRIS: Temenos Interaction, Reporting & Information Services

1. The Glory of REST
NEW TOOLS TO IMPROVE REST MATURITY

2. 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

3. 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.

4. REST Architecture

5. REST Maturity Model (Leonard Richardson)

6. 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

7. 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

8. Spring HATEOAS Example
@Controller
class 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);
}

9. 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);
}

10. Spring HATEOAS Conclusion
Allows to create links.
Integrates in Spring REST MVC
First step to hypermedia control

11. 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

12. 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**

13. 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

14. 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

15. 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

16. 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#/

17. 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