Software Development Done Right Rest in Depth Meetup

1. Software Development Done Right Rest in Depth Meetup Jan Vermeir Marco van der Linden

2. Agenda Introduction REST, HATEOAS and API design Our API Spring HATEOAS hands-on Atom Discussion

3. Introduction Jan Vermeir Marco van der Linden

4. REST Is an architectural style Described by Roy Fielding Defined via a set of constraints Uses web “standards” On the web, not tunneled through it

5. REST Principles Identifiable resources Uniform interface Resource representations Hypermedia (as the engine of application state) Stateless communication

6. Maturity Model

7. Hypermedia controls Hypermedia controls have three jobs: They tell the client how to construct an HTTP request: what HTTP method to use, what URL to use, what HTTP headers and/or entity-body to send. They make promises about the HTTP response, suggesting the status code, the HTTP headers, and/or the data the server is likely to send in response to a request. They suggest how the client should integrate the response into its workflow.

8. To level 3 in 5 steps Identify resources and design resource formats and URI’s. Give everything an ID (URI/URL) Identify state changes Select or design a hypermedia format. Link things to each other. Use standard web methods and select response codes. Allow for multiple representations Stefan Tilkov, "REST und HTTP"

9. Web API design Provide an entry point URI(like homepage) . Link to specific resources and create state transition links (user actions)

10. Some hypermedia formats XHTML HAL Siren Hydra JSON-API Collection+JSON OData UBER OR, create your own.

11. Examples - UBER

12. Examples - HAL

13. Examples – hydra and OData

14. Myorder Web API (part) URI Operation Media Type Description Links to HTTP Status Codes /api GET None API Starting point all orders, approvedorders 200 /orders GET application/hal+json List of orders each item is just a link to an order. No order details are shown 200 /orders/approved GET application/hal+json List of orders each item is just a link to an order. No order details are shown 200 /orders POST application/hal+json Add new Order (for approval) Returns order with link to Approve, link to Self 201 /orders/{id} DELETE Remove Order (use eTag) /orders/{id} PUT application/hal+json Update Order (use eTag) /orders/{id} GET application/hal+json Get Order /orders/{id}/approve POST application/hal+json Approve new Order /orders/{id}/reject POST application/hal+json Reject Order /products/...

15. Myorder Web API Discover the API starting from the API entry point starting at: http://localhost:9000/api Clone from: https://github.com/xebia/rest-in-depth-meetup

16. Spring HATEOAS Add support for hypermedia to exposed resources (ResourceSupport, Link) Build Links (ControllerLinkBuilder or EntityLinks) Create resources (ResourceAssemblerSupport) Expose resources (@EnableHypermediaSupport, @ExposesResourceFor) via Controllers * Link object follows the Atom link definition and creates a href and rel attribute. ** See https://github.com/spring-projects/spring-hateoas

17. Snippets from the example project Add support for hypermedia Build links in resource assemblers

18. Exercises 1 1. Start the myorder app ( Run com.orders.Application) and use a REST client to discover the API starting at http: //localhost:9000/ api. 2 Open https://github.com/spring-projects/spring-hateoas 3 2. Open the Product Controller and implement the removeProduct method. 3. Ensure that the Product Representation ( resource) contains a 4 Link to the vendor. Use ControllerLinkBuilder linkTo(). Next use LinkTo & MethodOn( ).Experiment with the various options. 4. Add a Link to vendor in the same Product Representation using EntityLinks. 5. Add a CurieProvider in com.orders.Application. 5 6

19. The state of Spring HATEOAS Still a work in progress. Only HAL is supported currently, but embedding resources requires custom coding (HALResource). Documentation is not very complete. For instance, no mention of ALPS support or how to use it. Not possible to link to resources outside of the classpath

20. Atom & ROME

21. Publish Changes Atom/RSS feed Client asks server for updates Client needs to remember last updated time Use HTTP if-modified-since header tag to limit data

22. Rome Rome formats data so it can be used by a feed reader Core concepts are - SyndFeed - SyndEntry See git@github.com:xebia/rest-in- depth-jaxrs.git

23. <DEMO> Fooling the Firefox Atom reader plugin …

24. Stefan Tilkov - http://rest-http.info/ Jim Webber • http://restinpractice.com/book/

25. Questions?

26. Solution exercise 2 @RequestMapping(method = RequestMethod.DELETE, value = "/{id}") public ResponseEntity<ProductResource> cancelProduct(@PathVariable String id) { boolean deleted = productRepository.delete(UUID.fromString(id)); if (!deleted) { return new ResponseEntity<ProductResource>(HttpStatus.NOT_FOUND); } else { return new ResponseEntity<ProductResource>(HttpStatus.OK); }

27. Solution Exercise 3 & 4 // TODO: add link to vendor using ControllerLinkBuilder resource.add(linkTo(methodOn(VendorController.class).viewVendor(product.getVendor().getId().toString())).withRel("vendor2")); // TODO: add link to vendor using entityLinks resource.add(entityLinks.linkToSingleResource(Vendor.class, product.getVendor().getId().toString()).withRel("vendor1"));

28. Solution exercise 5 @Bean public CurieProvider curieProvider() { return new DefaultCurieProvider("mo", new UriTemplate("http://myorder.com/relati ons/{rel}")); }

29. Myorder Web API List of Products Product products product Site List of Orders items List of Order Items orders approve