Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

RESTful services Design Lab

900 views

Published on

A sample application of a REST-based distributed system and the design and API of thta system

Published in: Internet
  • Be the first to comment

RESTful services Design Lab

  1. 1. REST DESIGN LAB PROGRAMAÇÃO DE SISTEMAS DISTRIBUÍDOS Paulo Gandra de Sousa pag@isep.ipp.pt
  2. 2. Lab #2 Retail
  3. 3. System architecture For argument sake let’s ignore payments
  4. 4. Use case: Process a customer order * 1. Find the nearest warehouse to the customer 2. if warehouse has enough inventory of the product 1. Reserve the product at the warehouse 2. Obtain a quote from each dispatcher 3. Order the dispatching service to wining bid 4. Confirm reservation at warehouse 3. Repeat 1-2 for “next” nearest warehouse until all itens are satisfied * (advanced) order may be split in several packages from different warehouses.
  5. 5. Tips  Don’t think about the user interface but instead think about “atomic” business operation requests  Authentication is outside of the application protocol  Decide on a base format, e.g., XML, JSON, HTML  Whenever possible use standard media types, e.g., vCard  Most resources will follow a collection/item pattern
  6. 6. Tips  Remember, each service is autonomous,  just because some resource has the same name it doesn’t mean it is the same kind of resource and has the same representations  Services don’t know and don’t have access to the internals of other services, e.g., database  Don’t expose implementation details  Don’t forget hypermedia
  7. 7. A solution This is one possible solution, based on lots of implicit assumptions and on the author’s personal opinions!
  8. 8. Main Services/Resources  Retail  Order  User  Geo  Distance  Warehouse  Order  Product  Dispatcher  Order  User  Supplier  Product  Order  User
  9. 9. Retail service Resource Description Order The collection of user orders POST – submit a new order Order/:id A specific user order GET – get the order details PUT – update the order DELETE – cancel the order Order/:id/shipping The shipping address of a specific order GET – get the shipping address PUT – change the order’s shipping address Order/:id/itens The ordered itens GET – get the ordered itens details POST – add a new item to the order Order/:id/itens/:idx A specific ordered item GET – get the order line details PUT – update the order line, e.g., quantity DELETE – remove the item from the order
  10. 10. Retail service (cont.d) Resource Description Product GET The product catalog (filtered, paged) Product/:id A specific product sold at the retail site GET – get the product details User The collection of registered users of the retail service POST – register a new user User/:uid A specific registered user GET – get the user details PUT – update the user details DELETE – remove account User/:uid/Address The collection of known addresses of a user GET, PUT, DELETE User/:uid/Address/:ai d A specific user address GET, PUT, DELETE User/:uid/orders GET The collection of orders from a specific user (filtered)
  11. 11. Submit a new order (request) POST /order { customer: CUSTOMER-URI, itens: [ { product: PRODUCT-URI, quantity: NUMBER, }, ... ], paymentAuth: OBJECT, billingAddress: CUST-ADDR-URI, shippingAddress: CUST-ADDR-URI, shippingMode: STRING, }
  12. 12. Submit a new order (response) 201 Created Location: http://myretail.com/order/123 { id: http://myretail.com/order/123 //ORDER-URI, customer: CUSTOMER-URI, packages: [ { itens: [ { product: PRODUCT-URI, quantity: NUMBER, }, ... ], expectDeliveryOn: DATE, }, ... ] paymentAuth: OBJECT, billingAddress: CUST-ADDR-URI, shippingAddress: CUST-ADDR-URI, shippingMode: STRING, cost: { amount: NUMBER, currency: STRING } status: STRING, acceptedOn: DATE, } Basic hypermedia for now
  13. 13. Order media type  shippingMode can have one of the following values “regular”, “express”, “overnight”  status can have one of the following values “pending”, “processing”, “transiting”, “delivered”, “fulfilled”  currency is an ISO 4217 code, e.g., EUR
  14. 14. Obtain a user’s list of orders GET /user/:uid/orders  Query parameters:  status – the status to filter, e.g., “pending”, “processing”, “transiting”, “delivered”, “fulfilled”  from - the starting date in YYYY-MM-DD format  to - the end date in YYYY-MM-DD format
  15. 15. Obtain a user’s list of orders (response) 200 Ok Location: http://myretail.com/user/123/orders { orders: [ ORDER-URI, ... ], filters: { status: STRING, from: DATE, to: DATE } } Returning just the index of orders but could return the complete order objects The active filters used for the GET. This might be duplicated information in the request.
  16. 16. GeoService  Location  GET  DistanceCalculator  POST  Typically we would use an existing geo service such as Bing, Google or Yahoo and not define our own service
  17. 17. Calculate distance (request) POST /DistanceCalculator { from: { type: STRING, LOCATION }, to: { ... }, options: [ OPTION ], }
  18. 18. Calculate distance  type indicates the kind of location info. Currently it can have the values “LatLong” and “address”  LOCATION if type = LatLong  {lat: STRING, log: STRING}  LOCATION if type = address  {country: STRING, address: STRING}  OPTION can have the values “fastest”, “eco”, “no-toll”
  19. 19. Warehouse service Resource Description Location GET The location of the warehouse Order The collection of warehouse orders POST Order/:id A specific warehouse order GET – get the order details PUT – update the entire order POST – confirms the reservation DELETE – cancel the order Order/:id/itens The ordered itens GET – get the ordered itens details POST – add a new item to the order Order/:id/itens/:idx A specific ordered item GET – get the order line details PUT – update the order line, e.g., quantity DELETE – remove the item from the order Product GET The product catalog Product/:id GET A specific product “available” at the warehouse Product/:id/inventory GET The current inventory of a product
  20. 20. Place an order (request) POST /order { customerOrder: CUSTOMER-ORDER-URI, itens: [ { product: PRODUCT-URI, quantity: NUMBER, }, ... ], }
  21. 21. Place an order (response) 201 Created Location: http://mywarehouse-1.com/order/123 { id: http://mywarehouse-1.com/order/123 , //ORDER-URI customerOrder: CUSTOMER-ORDER-URI, itens: [ { product: PRODUCT-URI, quantity: NUMBER, }, ... ], status: “reserved”, reservationExpiresOn: DATE, acceptedOn: DATE, expectReadyBy: DATE } This is not a Customer Order!! Basic hypermedia for now
  22. 22. Warehouse Order media type  status can have one of the following values “reserved”, “confirmed”, “processing”, “processed”, “picked-up”  The order is always created as a reservation with a time limit
  23. 23. No inventory 409 Conflict { reason: STRING, inventory: [ { product: PRODUCT-URI, stock: NUMBER, }, ... ], }
  24. 24. Confirm the reservation (request) POST /order/1234 { status: “confirmed” } Check HTTP PATCH
  25. 25. Confirm the reservation (response) 200 Ok { id: http://mywarehouse-1.com/order/123 , //ORDER-URI customerOrder: CUSTOMER-ORDER-URI, itens: [ { product: PRODUCT-URI, quantity: NUMBER, }, ... ], status: STRING, acceptedOn: DATE, expectReadyBy: DATE } reservationExpires is no longer part of the representation
  26. 26. Reservation expired 410 Gone
  27. 27. Dispatcher service  Order  POST  Order/:id  GET  POST  PUT  DELETE  User/:id  GET  PUT
  28. 28. Block execution until dispatcher sends the quotation? Definitely Not. Retail service should provide a callback for assynchronous communication. Or should poll the quote resource.
  29. 29. Non blocking communication Callback Polling
  30. 30. Ask for a quotation (request) POST /quote { myRef: CUSTOMER-ORDER-URI, pickup: ADDRESS, delivery: ADDRESS, volumes : [ {weight: NUMBER, height: NUMBER, width: NUMBER, depth: NUMBER}], serviceType: STRING, callback: URI, }
  31. 31. Ask for a quotation (response) 202 Accepted
  32. 32. Place a bid (request) POST /order/:id/quote/:id { id: http://dispatcher-1.com/quote/123 , //QUOTE-URI yourRef: CUSTOMER-ORDER-URI, itens: [ { product: PRODUCT-URI, quantity: NUMBER, }, ... ], cost: {amount: NUMBER, currency: STRING}, expiresOn: DATE, expectedPickup: DATE, expectedDelivery: DATE, }
  33. 33. Place a bid (response) 200 Ok OR 204 No Content
  34. 34. Place an order based on a quote (request) POST /order { quote: QUOTE-URI, packages: [STRING, …], pickup-contact : {name: STRING, phone: STRING, email: STRING}, delivery-contact : {name: STRING, phone: STRING, email: STRING}, }
  35. 35. Place an order based on a quote (response) 201 Created Location: http://dispatcher-1.com/order/765 { id: http://dispatcher-1.com/order/765 , //ORDER-URI yourRef: CUSTOMER-ORDER-URI, quote: QUOTE-URI packages: ... status: STRING, acceptedOn: DATE, cost: {amount: NUMBER, currency: STRING}, expectedPickup: DATE, expectedDelivery: DATE, }
  36. 36. Quote expired 410 Gone
  37. 37. Supplier  Order  POST  Order/:id  GET  POST  PUT  DELETE  Product  GET  Product/:id  GET  User/:id  GET  PUT

×