Transcript Rest in Depth presentation

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
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 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/...
Remove Order (use eTag)
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
(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
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 removeProduct
method.
4
3. Ensure that the Product Representation ( resource) contains a
Link to the vendor. Use ControllerLinkBuilder linkTo(). Next use
LinkTo & MethodOn( ).Experiment with the various options.
5
4. Add a Link to vendor in the same Product Representation using
EntityLinks.
6
5. Add a CurieProvider 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
Rome formats data so it can be used
by a feed reader
Core concepts are
- SyndFeed
- SyndEntry
See [email protected]: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
@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);
}
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"));
Solution exercise 5
@Bean
public CurieProvider curieProvider() {
return new
DefaultCurieProvider("mo",
new
UriTemplate("http://myorder.com/relati
ons/{rel}"));
}
Myorder Web API
List of
Products
Product
products
product
Site
List of
Orders
items
orders
approve
List of
Order
Items