Software Development Done Right Rest in Depth Meetup

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

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

Introduction Jan Vermeir Marco van der Linden

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

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

Maturity Model

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.

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"

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

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

Examples - UBER

Examples - HAL

Examples – hydra and OData

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 /orders/{id} PUT application/hal+json Update Order (use e. Tag) /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/. . . Remove Order (use e. Tag)

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

Spring HATEOAS Add support for hypermedia to exposed resources (Resource. Support, Link) Build Links (Controller. Link. Builder or Entity. Links) Create resources (Resource. Assembler. Support) Expose resources (@Enable. Hypermedia. Support, @Exposes. Resource. For) via Controllers * Link object follows the Atom link definition and creates a href and rel attribute. ** See https: //github. com/spring-projects/spring-hateoas

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

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 remove. Product method. 4 3. Ensure that the Product Representation ( resource) contains a Link to the vendor. Use Controller. Link. Builder link. To(). Next use Link. To & Method. On( ). Experiment with the various options. 5 4. Add a Link to vendor in the same Product Representation using Entity. Links. 6 5. Add a Curie. Provider in com. orders. Application.

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

Atom & ROME

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

Rome formats data so it can be used by a feed reader Core concepts are - Synd. Feed - Synd. Entry See git@github. com: xebia/rest-indepth-jaxrs. git

<DEMO> Fooling the Firefox Atom reader plugin …

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

Questions?

Solution exercise 2 @Request. Mapping(method = Request. Method. DELETE, value = "/{id}") public Response. Entity<Product. Resource> cancel. Product(@Path. Variable String id) { boolean deleted = product. Repository. delete(UUID. from. String(id)); if (!deleted) { return new Response. Entity<Product. Resource>(Http. Status. NOT_FOUND); } else { return new Response. Entity<Product. Resource>(Http. Status. OK); }

Solution Exercise 3 & 4 // TODO: add link to vendor using Controller. Link. Builder resource. add(link. To(method. On(Vendor. Controller. class). view. Vendor(product. get. Vendor(). get. Id(). to. String())). with. Rel("vendor 2")); // TODO: add link to vendor using entity. Links resource. add(entity. Links. link. To. Single. Resource(Vendor. class, product. get. Vendor(). get. Id(). to. String()). with. Rel("vendor 1"));

Solution exercise 5 @Bean public Curie. Provider curie. Provider() { return new Default. Curie. Provider("mo", new Uri. Template("http: //myorder. com/relat ions/{rel}")); }

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