MTAT Enterprise System Integration

Size: px

Start display at page:

Download "MTAT Enterprise System Integration"

Bathsheba King
5 years ago
Views:

1 MTAT Enterprise System Integration Lecture 6: Hypermedia REST Luciano García- Bañuelos University of Tartu

Richardson s Maturity Level 2 Also known as CRUD services Multiple URIs, multiple HTTP verbs, and HTTP Status Codes HTTP verbs GET, POST, PUT, DELETE HTTP

2 Richardson s Maturity Level 2 Also known as CRUD services Multiple URIs, multiple HTTP verbs, and HTTP Status Codes HTTP verbs GET, POST, PUT, DELETE HTTP Status Codes 1xx - Metadata 2xx Everything s fine 3xx Redirection 4xx Client did something wrong 5xx Server did a bad thing HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 1

3 Hypermedia within our application? HATEOAS: Hypermedia as the engine of application state Roy Fielding s view: The simultaneous presentation of information and controls such that the information becomes the affordance through which the user obtains choices and selects actions. A simpler wording: Include links into the resource representation. Let the user (human or program) continue the execution by following one of those links. HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 2

4 Hypermedia in the Web <a href=" title="view search page">search</a> <img src=" title="company logo"/> <form method="get"> <label>search term:</label> <input name="query" type="text" value=""/> <input type="submit"/> </form> <form method="post" action=" <label>keywords:</label> <input name="keywords" type="text" value=""/> <input type="submit"/> </form> HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 3

5 Hypermedia in the Web <a href=" title="view search page">search</a> Lazy loading (the user must explicit follow the link) Eager loading (the browser downloads the image without asking anything to the user) <img src=" title="company logo"/> HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 4

6 Hypermedia in the Web <form method="get"> <label>search term:</label> <input name="query" type="text" value=""/> <input type="submit"/> </form> GET /books/?query=rest HTTP/1.1 Host: POST /keywords HTTP/1.1 Host: Content- Type: application/x- www- form- urlencoded keywords=soap+rest+ws <form method="post" action=" <label>keywords:</label> <input name="keywords" type="text" value=""/> <input type="submit"/> </form> HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 5

7 H- Factors The H Factor of a media- type is a measurement of the level of hypermedia support and sophistication of a media- type M. Amundsen 1.Link Support [LE]Embedding links [LO]Outbound links [LT]Templated queries [LN]Non-Idempotent updates (POST) [LI]Idempotent updates (PUT/DELETE) 2.Control Data Support [CR]Control data for read requests (Accept header) [CU]Control data for update requests (Content-Type header) [CM]Control data for interface methods (HTTP verb) [CL]Control data for links (link relations) HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 6

8 H- Factor of popular REST media types factors/ HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 7

9 Example: PO creation (BuildIt) POST /orders BuildIt <purchaseorder> <start> </start> <end> </end> <plant> <name>excavator</name> <plant> </purchaseorder> RentIt HTTP/1.1 Location: 201 Created /orders/1253 HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 8

10 Example: RentIt s view GET /orders/ HTTP/ Ok RentIt <purchaseorder> <startdate> </startdate> <endend> </endend> <cost> </cost> <plant> <sku>exc1253ab98</sku> <name>excavator</name> <plant> <links> <link rel="accept" href="/orders/1253/accept" method="post"/> <link rel="reject" href="/orders/1253/accept" method="delete"/> </links> </purchaseorder> HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 9

11 Our example application PurchaseOrderRestController POExtRequestResource enddate: Date status: ExtStatus PurchaseOrderResource startdate: Date enddate: Date total: Money status: POStatus PlantInvEntryResource name: String description: String price: Money PurchaseOrderService createpurchaseorder() acceptpurchaseorder() rejectpurchaseorder() resubmitpurcherorder() extendrentalperiod() acceptrentalperiodextension() rejectrentalperiodextension() Customer PlantReservation PlantInvEntry <<Enumeration>> POStatus PENDING OPEN PENDING_EXTENSION CLOSED REJECTED <<Enumeration>> ExtStatus 1 customer 0..* reservations PurchaseOrder plant OPEN extensions ACCEPTED startdate: Date REJECTED enddate: Date * total: Money status: POStatus 1 name: String description: String price: Money POExtensionRequest enddate: Date status: ExtStatus HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 10

12 Our example application PurchaseOrderRestController POExtRequestResource enddate: Date status: ExtStatus PurchaseOrderResource startdate: Date enddate: Date total: Money status: POStatus PlantInvEntryResource name: String description: String price: Money PurchaseOrderService createpurchaseorder() acceptpurchaseorder() rejectpurchaseorder() resubmitpurcherorder() extendrentalperiod() acceptrentalperiodextension() rejectrentalperiodextension() Customer PlantReservation PlantInvEntry <<Enumeration>> POStatus PENDING OPEN PENDING_EXTENSION CLOSED REJECTED name: String 1 customer 0..* reservations description: String <<Enumeration>> plant price: Money 1 ExtStatus PurchaseOrder OPEN POExtensionRequest extensions ACCEPTED startdate: Date REJECTED enddate: Date * enddate: Date total: Money status: ExtStatus status: POStatus HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 11

13 Resource life cycle: Purchase order PurchaseOrderService createpurchaseorder() acceptpurchaseorder() rejectpurchaseorder() resubmitpurcherorder() extendrentalperiod() acceptrentalperiodextension() rejectrentalperiodextension() createpo rejectpo pending confirmation rejected resubmitpo acceptpo acceptrpextension open closepo closed rejectrpextension extendrentalperiod pending extension HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 12

14 Hypermedia API rejectpo rejected createpo pending confirmation acceptpo open Verb URI template Relation Current state New state Comments POST /orders createpo Pending confirmation POST /orders/{oid}/accept acceptpo Pending confirmation DELETE /orders/{oid}/accept rejectpo Pending confirmation Open Rejected Submit partial representation Use empty body HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 13

15 Full Purchase Order API Method URI template Relation Current state New state Comments POST /orders createpo Pending confirmation POST /orders/{oid}/accept acceptpo Pending confirmation DELETE /orders/{oid}/accept rejectpo Pending confirmation Open Rejected PUT /orders/{oid} resubmitpo Rejected Pending confirmation DELETE /orders/{oid} closepo Open Closed POST /orders/{oid}/extensions extendrentalperiod Open Pending update POST DELETE /orders/{oid}/extensions /{eid}/accept /orders/{oid}/extensions /{eid}/accept acceptrpextension rejectrpextension Pending update Pending update Open Open Submit partial representation Use empty body Submit new full representation Submit new end date Use empty body HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 14

16 Annotated State model DELETE /orders/{oid}/accept rejectpo rejected POST /orders createpo pending confirmation PUT /orders/{oid} resubmitpo POST /orders/{oid}/extensions/{eid}/accept acceptrpextension open POST /orders/{oid}/accept acceptpo DELETE /orders/{oid} closepo closed DELETE /orders/{oid}/extensions/{eid}/accept rejectrpextension POST /orders/{oid}/extensions extendrentalperiod pending extension HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 15

Annotated State model Events produced by BuildIt DELETE /orders/{oid}/accept rejectpo rejected POST /orders createpo pending confirmation PUT /orders/{oid} resubmitpo POST

17 Annotated State model Events produced by BuildIt DELETE /orders/{oid}/accept rejectpo rejected POST /orders createpo pending confirmation PUT /orders/{oid} resubmitpo POST /orders/{oid}/extensions/{eid}/accept acceptrpextension open POST /orders/{oid}/accept acceptpo DELETE /orders/{oid} closepo closed DELETE /orders/{oid}/extensions/{eid}/accept rejectrpextension POST /orders/{oid}/extensions extendrentalperiod pending extension HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 16

18 Implementing the Hypermedia API REST LUCIANO GARCÍA- BAÑUELOS 17

Changes on resource classes @Entity @Data public class Plant { private String name;

model In this case, we will use the library spring- hateoas.

our previous version. Note that we will use JSON as the representation format.

name; private String description; private Double price; } Package: ~.application.

19 Changes on public class Plant { private String name; private String description; private Double price; } Package: ~.domain.model In this case, we will use the library spring- hateoas. However, the classes required and their implementation are quite similar to those in our previous version. Note that we will use JSON as the public class PlantResource extends ResourceSupport { private String name; private String description; private Double price; } Package: ~.application.dto Maven dependency Group id: org.springframework.hateoas Artifact id: spring- hateoas Version: RELEASE REST LUCIANO GARCÍA- BAÑUELOS 18

Resource assembler public class PlantResourceAssembler extends ResourceAssemblerSupport<Plant, PlantResource> { public PlantResourceAssembler() { super(plantrestcontroller.class, PlantResource.

20 Resource assembler public class PlantResourceAssembler extends ResourceAssemblerSupport<Plant, PlantResource> { public PlantResourceAssembler() { super(plantrestcontroller.class, PlantResource.class); } public PlantResource toresource(plant plant) { PlantResource resource; resource = createresourcewithid(plant.getid(), plant); resource.setname(plant.getname()); resource.setdescription(plant.getdescription()); resource.setprice(plant.getprice()); return resource; } HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 19

REST service façade (creation) @RestController @RequestMapping("/api/orders") public class PurchaseOrderRESTController { @Autowired PurchaseOrderService service; @RequestMapping(method =

pending_confirmation); service.createpo(po); HttpHeaders headers = new HttpHeaders(); URI uri = linkto(purchaseorderrestcontroller.class).slash(po.getid()).touri(); headers.

21 REST service public class PurchaseOrderRESTController PurchaseOrderService = RequestMethod.POST, value = "") public ResponseEntity<PurchaseOrderResource> createpo(@requestbody PurchaseOrder po) throws PlantUnavailableException { po.setstatus(postatus.pending_confirmation); service.createpo(po); HttpHeaders headers = new HttpHeaders(); URI uri = linkto(purchaseorderrestcontroller.class).slash(po.getid()).touri(); headers.setlocation(uri); } PurchaseOrderResource pors = assembler.toresource(po); ResponseEntity<PurchaseOrderResource> response; response = new ResponseEntity<>(poRs, headers, HttpStatus.CREATED); return response; } HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 20

REST service façade (retrieval) @Controller @RequestMapping("/api/orders") public class PurchaseOrderRESTController { @RequestMapping(method = RequestMethod.

22 REST service public class PurchaseOrderRESTController = RequestMethod.GET, value = "{id}") public ResponseEntity<PurchaseOrderResource> getpo(@pathvariable Long id) { PurchaseOrder po = PurchaseOrder.findPurchaseOrder(id); PurchaseOrderResourceAssembler assembler = new PurchaseOrderResourceAssembler(); PurchaseOrderResource resource = assembler.toresource(po); switch (po.getstatus()) { case PENDING_CONFIRMATION: Method _acceptpo = PurchaseOrderRESTController.class.getMethod("acceptPO", Long.class); String acceptlink = linkto(_acceptpo, po.getid()).touri().tostring(); resource.add(new ExtendedLink(acceptLink, "acceptpo", "POST")); Method _rejectpo = PurchaseOrderRESTController.class.getMethod("rejectPO", Long.class); String rejectlink = linkto(_rejectpo, po.getid()).touri().tostring(); resource.add(new ExtendedLink(rejectLink, "rejectpo", "DELETE")); break; default: break; } } } ResponseEntity<PurchaseOrderResource> response; response = new ResponseEntity<>(resource, HttpStatus.OK); return response; HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 21

23 Exception handling HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 22

Example GET /orders/1253 http://rentit.com/api HTTP/1.1 200 Ok <purchaseorder>...</purchaseorder> HTTP/1.

24 Example GET /orders/ HTTP/ Ok <purchaseorder>...</purchaseorder> HTTP/ Not found RentIt HTTP/ Unauthorized HTTP/ Internal Server Error HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 23

25 Exception handling & HTTP status codes 400 Bad Request The client has PUT or POST a resource representation that is in the right format, but contains invalid information 401 Unauthorized Proper credentials to operate on a resource were not provided Response WWW-Authenticate header contains the type of authentication the server expects Basic, digest, WSSE, etc. 403 Forbidden The client request is OK, but the server doesn t want to process it (e.g., Restricted by IP address) HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 24

26 Exception handling & HTTP status codes 404 Not Found The standard catch- all response 405 Method Not Allowed The resource does not support a given method. Use Allow header to list the verbs the resource understands (e.g., Allow: GET, POST, PUT) 409 Conflict Tried to change the state of the resource to something the server will not allow HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 25

27 Exception handling & HTTP status codes 406 Not Acceptable The server cannot reply with the representation requested by the client HTTP header Accept 415 Unsupported Media Type The server cannot consume the resource format used by the client HTTP header Content-type HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 26

Exception handling within our REST controller @RestController @RequestMapping("/rest/orders") public class PurchaseOrderRESTController { } @ExceptionHandler({PlantUnavailableException.

28 Exception handling within our public class PurchaseOrderRESTController { InvalidHirePeriodException.class}) public ResponseEntity<String> handlebadrequest(exception ex) { return new ResponseEntity<>(ex.getMessage(), HttpStatus.CONFLICT); public ResponseEntity<String> handlenotfound(exception ex) { return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND); } HYPERMEDIA REST LUCIANO GARCÍA- BAÑUELOS 27

MTAT Enterprise System Integration

MTAT Enterprise System Integration MTAT.03.229 Enterprise System Integration Lecture 7: Hypermedia REST Luciano García-Bañuelos University of Tartu Richardson s Maturity Level 2 Also known as CRUD services Mul5ple URIs, mul5ple HTTP verbs,