Real-World RESTful Service Development Problems and Solutions
2 likes2,839 views
The document discusses the development challenges and solutions related to real-world RESTful services, focusing on best practices, resource design, and performance optimizations. It covers key topics such as authentication, caching strategies, asynchronous processing, and error handling, all while providing practical coding examples. The text emphasizes the importance of adhering to REST principles and considers emerging standards and design patterns for effective service development.
![ParKal
Updates
&
HTTP
PATCH
JavaScript
Object
NotaTon
(JSON)
Patch,
RFC
6902
Copyright
©
2014,
Oracle
and/or
its
affiliates.
All
rights
reserved.
|
• ParKally
update
a
JSON
document
• Works
with
HTTP
PATCH
• Requires
special
body
syntax
and
direcKves
PATCH
/coffee/orders/1234
HTTP/1.1
Host:
api.foo.com
Content-‐Length:
100
Content-‐Type:
applicaKon/json-‐patch
[
{“op”:"replace",
”path”:
"/status",
"value":
"COMPLETED"}
]](https://image.slidesharecdn.com/javazonebof21052-141002115701-phpapp02/85/Real-World-RESTful-Service-Development-Problems-and-Solutions-34-320.jpg)
Real-World RESTful Service Development Problems and Solutions
- 2. Real-‐World RESTful Service Development Problems and SoluKons Masoud Kalali, SoNware Engineer at ORACLE, @MasoudKalali Copyright © 2014, Oracle and/or its affiliates. All rights reserved. |
- 3. Safe Harbor Statement The following is intended to outline our general product direcKon. It is intended for informaKon purposes only, and may not be incorporated into any contract. It is not a commitment to deliver any material, code, or funcKonality, and should not be relied upon in making purchasing decisions. The development, release, and Kming of any features or funcKonality described for Oracle’s products remains at the sole discreKon of Oracle. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. |
- 4. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Program Agenda IntroducKon Basics of RESTful services and Java What to consider when designing resources A liWle bit of security Performance maWers! More common paWerns Emerging standards 1 2 3 4 5 6 7
- 5. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Speaker • Masoud Kalali • SoNware engineer, author, blogger… • Listens to high definiKon Audio (you got what I mean) • @MasoudKalali
- 6. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | IntroducKon Basics 1. REST basic best pracKces 2. Java and REST Problems and Pa;erns 1. Common problems and soluKons 2. A liWle dive into emerging standards
- 7. Basics of RESTful services and Java REST Basics Java Standard API for REST Resource Design Response Desing Copyright © 2014, Oracle and/or its affiliates. All rights reserved. |
- 8. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | REST Basics What is REST? • The idea • Unified predictable interface • Maturity of the underlying protocols • The ease of use • Vast and expanding adopKon • Age of Apps
- 9. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Resource Design paWerns How to design the resources? • Resources – names – path formaKon • Verbs – Idempotency – Safety, Cache-‐ability GET hWp://cdom.com/api/v1/customers/1 GET hWp://cdom.com/api/v1/customers/1/orders/1 Not Good: GET hWp://cdom.com/api/v1/customers/1?delete=true POST hWp://cdom.com/api/v1/customers/1?delete=true
- 10. HTTP verbs: Idempotency and safety Verb Ideompotency Safety Cached Data/URI length limit GET ✔ ✔ ✔ Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | 2048 Characters PUT ✔ ✗ ✗ No Limit POST ✗ ✗ ✗ No Limit DELETE ✔ ✗ ✗ Depends* PATCH** ✗ ✗ ✗ No Limit How to design the resources? • * Some older HTTP servers, proxies may reject a DELETE request which carry payload. • ** Not supported by all hops
- 11. Request/Response paWerns How should a resource respond to a request? Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | • Response status codes – There are more than 200, 404 and 500! • Unified response style – Predictability of response body – ApplicaKon specific error code – Human readable message – cause/soluKon
- 12. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Java Standard API for REST What Java has to say here? • Long available HTTP client libraries • Long available Servlets • Recent adopKon of POJO to resources mapping, JAX-‐RS… • Recent standardizaKon of resource clients • BeWer integraKon and use of JSON • Incredible number of libraries and frameworks
- 13. Basics of RESTful services and Java Code and Demo Tme! Copyright © 2014, Oracle and/or its affiliates. All rights reserved. |
- 14. Request and Response…. Content NegoTaTon Resource Versioning ValidaTon ExcepTon Handling Copyright © 2014, Oracle and/or its affiliates. All rights reserved. |
- 15. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Content NegoKaKon Flexible response types • Produce mulKple types of response – JSON – XML – HTML • Produce mulKple semanKcally different response – Based on user agent – Based on custom/domain oriented media types – Base on both
- 16. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Content NegoKaKon JAX-‐RS and flexible response types • On the server side – @Produce • Should have matching media-‐type with request accept header • Non matching results in 406 -‐ Not Acceptable – @Consume • Should have matching media-‐type with request content-‐type header • Non matching results in 415 -‐ Unsupported Media Type • On the client side – Set correct content-‐type – Set expected accept header
- 17. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Resource Versioning How to evolve a resource? • Request and or response evolves to be incompaKble • Business semanKc evolves to become incompaKble • Version added to resource (URI) – Client is locked to the version • Problems like linked resource address stored in client side… • Version is negoKated as part of the request – Serve code need to handle all supported previous versions • No version, the big bang migraKon – Too costly for clients – Too hard to coordinate
- 18. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | ValidaKon ValidaTon before acTon! • ValidaKon goes with versioning and content negoKaKon • Unified validaKon paWerns across the codebase – Codified response format – Unified response body • Use annotaKons and standard validaKon as much as possible – Supports common media-‐types – Unified with custom coding/template being added
- 19. There are always unforeseen corner cases! Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | ExcepKon Handling • Please don’t send back stack trace – Use an ExcepKonMapper as Provider as last line of cleanup! – Unless in development environment (with some consideraKons) • Codify all failures and include cause/acKon in the response – Use right hWp status code – Add applicaKon level code for codifying issues – Add human understandable message
- 20. What to consider when designing resources Code and Demo Tme! Copyright © 2014, Oracle and/or its affiliates. All rights reserved. |
- 21. A liWle bit of security AuthenTcaTon Access control AudiTng Copyright © 2014, Oracle and/or its affiliates. All rights reserved. |
- 22. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | AuthenKcaKon Know who is requesTng a resource • AuthenKcaKon enabled for all resources • Happens before any other validaKon • Exclude the resource paWerns that requires no authenKcaKon • No access without validaKng the authenKcaKon token
- 23. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Access control Check who can access a resource • Happens aNer detecKng a valid authenKcaKon • Requests are easy to check – Unless column level checks are required, can be done in simple filter – Column level access control can be done using media types • Happens before any validaKon – unless params are being used as part of the access check
- 24. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | AudiKng/ Access logs Keep record of security incidents! • Keep a rich access log – Depending on the server you use • Include the usual who, when, what • Try using W3C Extended Log File Format if supported by server • Configure security realm for logging • Think ahead about incident detecKon/isolaKon, etc.
- 25. A liWle bit of Security Code and Demo Copyright © 2014, Oracle and/or its affiliates. All rights reserved. |
- 26. Performance maWers! Caching ParTal Updates & HTTP PATCH Asynchronous And long running jobs in REST Copyright © 2014, Oracle and/or its affiliates. All rights reserved. |
- 27. Being sTngy with the resource usage is OK! Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Caching • Local Cache • Proxy Cache • reverse-‐proxy (cache) • Server(ApplicaTon) Level Cache
- 28. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Caching ApplicaTon Level Cache • Use HTTP caching features • Client aware of provided caching support • Server evaluate caching related headers • intermediately hops • Types of Caching Headers – Absolute Caching Headers – CondiKonal Caching Headers
- 29. Cache Control DirecTves Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Caching Absolute Caching • From Server side: – Cache-‐Control and direcKves – Last-‐Modified HTTP/1.1 200 OK Content-‐Type: applicaKon/json Cache-‐Control: private, max-‐age=86400 Last-‐Modified: Thur, 01 Apr 2014 11:30 PST • private • public • no-‐cache • no-‐store • max-‐age (overrides Expires)
- 30. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Caching CondiTonal Caching • From client side send headers: – If-‐None-‐Match = "If-‐None-‐Match" ":" ( "*" | 1#enKty-‐tag ) – If-‐Modified-‐Since = "If-‐Modified-‐Since" ":" HTTP-‐date • At the server side produce headers: – Etag, when last-‐modified is hard to determine HTTP/1.1 200 OK Content-‐Type: applicaKon/json Etag: "8b329b598fcdad4fd33432e78128da48f72198829640882”
- 31. @GET @Consumes({JSON_TYPE}) @Produces({JSON_TYPE, MediaType.APPLICATION_JSON, MediaType.TEXT_PLAIN}) @Path("simple") public Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Response myGeWer(@PathParam("simple") int id, @Context Request request) { Simple simple = new Simple(id,"John", "Due", new Date()); if (request.evaluatePrecondiKons(simple.getLastModified()) == null) { CacheControl cacheControl = new CacheControl(); cacheControl.setMaxAge(3600); cacheControl.setPrivate(true); Response.ResponseBuilder responseBuilder = Response.ok(simple); responseBuilder.cacheControl(cacheControl).lastModified(simple.getLastModified()); EnKtyTag enKtyTag = new EnKtyTag(getEtagFor(simple), false); return responseBuilder.tag(enKtyTag).build(); } return Response.notModified().build(); } curl -‐v -‐X GET -‐H "Content-‐Type:applicaKon/json" -‐H "Accept:applicaKon/json" -‐H "If-‐Modified-‐Since:Mon, 08 Sep 2014 15:08:27 GMT" hWp://.../simple/1
- 32. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Caching More on Caching • Can be used for conflict resoluKon • Cache on GET request • Invalidate cache on PUT, POST or DELETE • Periodically purge cache entries • Cache invalidaKon, evicKon is not determinisKc • Give hWp://www.jboss.org/resteasy a try – Provides @Cache and @NoCache – Extension to JAX-‐RS
- 33. ParKal Updates & HTTP PATCH Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Only update what needs to be updated! • ParKal Updates with PUT • ParKal Updates with POST • ParKal updates with PATCH • JSON Patch is the future
- 34. ParKal Updates & HTTP PATCH JavaScript Object NotaTon (JSON) Patch, RFC 6902 Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | • ParKally update a JSON document • Works with HTTP PATCH • Requires special body syntax and direcKves PATCH /coffee/orders/1234 HTTP/1.1 Host: api.foo.com Content-‐Length: 100 Content-‐Type: applicaKon/json-‐patch [ {“op”:"replace", ”path”: "/status", "value": "COMPLETED"} ]
- 35. ParKal Updates & HTTP PATCH JavaScript Object NotaTon (JSON) Patch, RFC 6902 Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | • Supports six operaKons in the payload – op : can be “add”, “replace”, “move”, “remove”, “copy” or “test” • Another three aWributes to describe the op – path: LocaKon of the target aWribute in the JSON document – value: The new value to be added or to replace another – from: (Only for move op) specifies the source locaKon
- 36. Asynchronous And long running jobs in REST Don’t keep unnecessary resources for where not needed! • On Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | the serverside: – @Asynchronous: Annotate a sub-‐resource as Asynchronous – AsyncResponse: Provides results an acKons on the running request • seng Kmeout • registering callbacks • resume, cancel suspended request processing • updaKng the response – @Suspended: To inject a suspended AsyncResponse into a sub-‐resource parameter
- 37. Asynchronous And long running jobs in REST • On Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Server side callbacks the serverside: – CompleKonCallback: Async response processing compleKon callback • Response processing completed and sent to client • Response processing failed with excepKon – ConnecKonCallback: Client server connecKon events callback • Client is disconnected abruptly (before or during wriKng back the response)
- 38. Asynchronous And long running jobs in REST Client Code: Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Some small sample code @GET @Produce(“applicaKon/json”) @Asynchronous public void getOrder(@Suspended AsyncResponse ar, String orderId) { final String result = prepareResponse(orderId); ar.resume(result) } Future<Coffee> future = client.target(“/coffees/orderId") .request() .async() .get(Coffee.class); try { Coffee coffee = future.get(30, TimeUnit.SECONDS); } catch (TimeoutExcepKon ex) { // } Server Code: ** AlternaKve to Future is using InvocaKonCallback to get called when response is back
- 39. Asynchronous And long running jobs in REST Don’t keep unnecessary resources for where not needed! Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | • Send 202 where response is not ready with LocaKon header – Intelligent enough client can query the resource locaKon with the given Retry-‐Aier header – Beware of transacKonal mulK step long running tasks • Use message queues to process tasks in background
- 40. Performance maWers! Code and Demo Copyright © 2014, Oracle and/or its affiliates. All rights reserved. |
- 41. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Few more topics Response PaginaTng Usage Thro;ling REST and plug-‐ability and extensibility
- 42. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Response PaginaKng Paginate the record sets when possible • Offset based paginaKon – Page and limit • Cursor based paginaKon – A pointer to the next and previous set – Possible use of HATEOAS • Time based paginaKon – Since and to for indicaKng a Kme based query
- 43. Response PaginaKng PaWerns Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Paginate the record sets when possible • Include defaults incase client does not specify page number and number of results per page • Include meta data in response so client knows what is the next set of results to navigate to
- 44. Keep tap on how many request one user can send! Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | ThroWling PaWerns • Why use Rate LimiKng? – Prevent and handle abuse – Provide beWer support for premium users • How Rate LimiKng works? – Servlet filter sits in front – User user tokens or IP addresses as idenKfiers – Use in-‐memory cache for book keeping – Prevents requests reaching endpoints when limit reached – Reset update cached counters when needed
- 45. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | ThroWling PaWerns Headers and response • Response status, headers – HTTP 429 Too Many Requests error code – Retry-‐ANer header – X-‐RateLimit-‐Limit: ### – X-‐RateLimit-‐Remaining: ### – X-‐RateLimit-‐Reset: EPOCH_SECONDS • DescripKve response in the requested media type
- 46. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | ThroWling PaWerns Best pracTces • Client side – Use caching – keep tap on number of requests – Pay aWenKon to headers – No brainless loops (polling) • Server side – Support caching (etags and max-‐age) – provide streaming endpoints when possible (feeds, news, public data)
- 47. REST and plug-‐ability and extensibility Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Micro services design pa;ern! • Micro services vs Monolithic services • Advantages – Simplicity – IsolaKon of problems – Scale up and Scale down – Easy deployment – Clear SeparaKon of concerns
- 48. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | REST extensibility How is REST extensbile? • Uniform interface constraint • Standard HTTP methods • Well defined representaKons of resources • Easy to use by myriad of clients from web, to mobile clients to other applicaKons • Improves scalability, visibility and reliability
- 49. A liWle of advanced topics Code and Demo Copyright © 2014, Oracle and/or its affiliates. All rights reserved. |
- 50. Emerging standards WebSockets, Web hooks, etc. The role of REST in a future evolving web standards Copyright © 2014, Oracle and/or its affiliates. All rights reserved. |
- 51. WebSockets, Web Hooks, etc. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | RESTful services brethren! • WebSockets • WebHooks • ServerSentEvents
- 52. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | WebSockets RESTful services brethren! • Full duplex communicaKon over TCP • IniKal Handshake over HTTP for Upgrade request • Use when full duplex communicaKon is required
- 53. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | WebHooks RESTful services brethren! • User defined custom HTTP callbacks • Event producer sends event to the endpoint provided by client • Github WebHooks
- 54. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | ServerSentEvents RESTful services brethren! • Streaming model where clients get automaKc updates from server • One direcKon communicaKon from the server • QOS direcKves can be added to the message
- 55. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Comparisons Criteria WebHooks WebSockets SSE Long lived open connecKon Y Y Callback URI registered Y BidirecKonal Y Needs Fallback to Polling Y Asynchronous real Kme Y Y Y communicaKon Easy to implement Y Needs browser and proxy servers support Y RESTful services brethren!
- 56. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Emerging standards Code and Demo
- 57. Comments, QuesKons? Copyright © 2014, Oracle and/or its affiliates. All rights reserved. |
- 58. Copyright © 2014, Oracle and/or its affiliates. All rights reserved. | Resources • RESTful Services Patterns and best practices By Bhakti Mehta, http://www.amazon.com/RESTful-‐Java-‐Patterns-‐Best-‐Practices/dp/1783287969/ • http://tools.ietf.org/html/rfc6902 • http://tools.ietf.org/html/rfc6901 • http://resteasy.jboss.org/ • https://jersey.java.net/documentation/latest/ • http://tools.ietf.org/html/rfc6585 • http://tools.ietf.org/html/rfc5789 • CCL photos used in slides: • https://www.flickr.com/photos/treehouse1977/2892417805/ • https://www.flickr.com/photos/treehouse1977/2892417805/ • https://www.flickr.com/photos/essjay/165928100/ • https://www.flickr.com/photos/jforth/4413370462/ • https://www.flickr.com/photos/sakalak/8737872379/ • https://www.flickr.com/photos/jbparrott/8980026600 • https://www.flickr.com/photos/pentadact/36593493/ • https://www.flickr.com/photos/jasohill/4442279347/ • https://www.flickr.com/photos/mdsharpe/5075953655 • https://www.flickr.com/photos/chuqvr/8329512894/ • https://www.flickr.com/photos/longo/2684733921 • https://www.flickr.com/photos/_davor/14757399908
Editor's Notes
- #8: This slide can also be used as a Q and A slide
- #14: This slide can also be used as a Q and A slide
- #15: This slide can also be used as a Q and A slide
- #18: Explain which industry is more suited to use which schema
- #21: This slide can also be used as a Q and A slide
- #22: This slide can also be used as a Q and A slide
- #26: This slide can also be used as a Q and A slide
- #27: This slide can also be used as a Q and A slide
- #29: 304
- #41: This slide can also be used as a Q and A slide
- #42: This slide can also be used as a Q and A slide
- #50: This slide can also be used as a Q and A slide
- #51: This slide can also be used as a Q and A slide
- #57: This slide can also be used as a Q and A slide