the glory of rest in java: spring hateoas, raml, temenos iris
Post on 10-May-2015
5.256 Views
Preview:
DESCRIPTION
TRANSCRIPT
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
top related