Developing RESTful Services in Java

Size: px

Start display at page:

Download "Developing RESTful Services in Java"

Caitlin Armstrong
6 years ago
Views:

2 Note: Course 563 is available in multiple variants 563-GF, 563-WF, etc. each of which has been tested, tuned, and edited to support a specific target server in the classroom. This document offers guidance to the instructor for all of the variants, and so there will be some notes that may or may not apply to your class. Most of the content here is applicable to all variants, and where something is server-specific, I say so. Overview This course covers REST and JAX-RS, and essentially using the latter to build web services according to the former. It is for the most part a Java technology course, and as in most Capstone courses we focus on the EE standard and put a fairly high value on portability. But the course starts with an overview of REST and we take things like the maturity model seriously, and so throughout the course there are best-practice discussions and pointers on how to use JAX-RS to build services that could be considered RESTful in the best sense of the term. REST is evolving, and there are different styles. As Capstone materials are generally aimed at large IT enterprises, in this course we focus on common enterprise uses, and so development of patterns for CRUD operations is a major theme. We treat use of query parameters, headers, cookies, etc. But about as quickly as we can we move into heavier use of the HTTP entity. We consider both XML and JSON, JAXB and non-jaxb approaches, and try to give each due consideration. But then we settle on JSON without a JAXB requirement (although with observation of JAXB metadata where it appears). This seems to be the way the world is headed and so we put more weight there as the course proceeds into intermediate and advanced topics such as error handling, validation, generics, etc. Another style question is that of hypermedia. This is probably the most debated area of REST, and as I say in the course not every company is ready to commit to it, preferring to stay in the more familiar space of HTTP entities as traditional transfer objects. It s not clear, either, how well JAX-RS supports hypermedia implementation. My approach to this has been to discuss hypermedia/hateoas and to try to clarify it as an alternative; then mostly to stick to level 2 or maybe 2½ of the maturity model, shying away from a rigorous hypermedia approach; and then toward the end of the course to present an interesting exercise in using entity interceptors to linkify responses. Hopefully it is enough to get students thinking seriously about hypermedia, even if we don t go whole-hog in the course exercises. 2

3 Timeline The following timings are approximate, and every class will be a little different. If time is short, there are a number of chapters that might be cut or shortened, depending on the group s particular interests: consider any of the last three chapters or the chapter on JPA and working with persistent data. Day 1 3 hours Chapter 1 2 hours Chapter 2 2½ hours Chapter 3 (spans days) Day 2 1 hour Chapter 4 2 hours Chapter 5 3 hours Chapter 6 (spans days) Day 3 2½ hours Chapter 7 2½ hours Chapter 8 2½ hours Chapter 9 (spans days) Day 4 2½ hours Chapter 10 2½ hours Chapter 11 1½ hours Chapter 12 Day 5 2 hours Chapter 13 2 hours Chapter 14 2 hours Chapter 15 3

4 Tools Deployed with the Lab Software This course s software requires a separate setup of JDK 7, and optionally the Crimson text editor and/or Eclipse. GlassFish and JBoss variants each rely on the additional setup of the relevant server, as directed in the classroom setup guide. The labs bundle all other required tools and libraries. These will all be found in directories under c:/capstone/jax-rs/tools as described in the Tools page(s) early in the coursebook. Tools needed vary by target server: the primary version carries Tomcat 7.0 as one of the tools and also requires Ant, Derby, EclipseLink, JSTL, and Weld bundles. The GlassFish and WildFly variants require none of these as they are all deployed with the server. Ant Build Process Though most students will either use Eclipse exclusively or will be happy to let the ant command take care of things, some will want to understand the inner workings here a little better. Each web project in the course has its own build.xml and build.properties files; these rely on centralized targets and properties files to define a routine for building the application and for deploying/undeploying as necessary from the server. There are also targets for supporting processes such as creating databases, configuring the server with data sources, message queues, user records, etc. These are all identified as necessary in the coursebook. For a better look under the hood, see that build.xml imports a series of properties and targets files in a central directory Ant. Some of these targets files import each other as well, forming a loose chain. All the logic for building and deploying can be found here. 4

5 Teaching Notes I hope that the coursebook is sufficiently clear and detailed, and so the following notes just capture a few ideas about how to approach a given topic, additional concepts to add to your lectures and discussions, and any surprises you might encounter. Chapter 1 In this chapter I m looking to lay out the big ideas of REST so as to set the stage for what is mostly a course in how to build services, using JAX-RS. There s a lot to talk about, and we need to introduce JAX-RS itself, if only briefly, and want to get in one simple, working exercise. To make things concrete as early as possible, I ve put that working exercise about mid-way through the chapter. This meant separating discussions of both REST and JAX-RS into two parts, so you will take a second pass at each and bring in new concepts content types, hypermedia, JAX-RS providers, etc. On paper this isn t the most direct possible flow; but the idea is that it should make for a better rhythm in class, instead of trying to roll through all of this material before giving students any chance to play with it. There s definitely more to REST practice, and we stop where we do in order to let students get going on practical exercises. Sub-resources and appropriate HTTP responses in error conditions are covered in depth later in the course; range requests, composite keys, and other finer points of API design are left out of scope, but you may want to discuss informally based on your own experience. 5

6 Chapter 2 We don t dwell on it but you might want to delve into more of the implications of the choice between request-scope and singleton resources there are effects on sharing of other objects and resources, and there s a small cost to creating new resource objects on each request, and then there can be threading concerns in singleton resource classes, too. This is just one more reason why the per-request approach, which to most students seems strange at first, is the primary emphasis of JAX-RS and generally is the way to go. Students may begin to notice as you move through the course that we don t take much advantage of the option to let the JAX-RS provider discover our root resources and providers, and they may wonder why. I wouldn t suggest bringing this up unless asked, because it goes pretty deep into some foibles of the tools we happen to use in the course. But a not-too-long version of the story is this: in a few of our services, we need to support requests at the root application path, either to pipe out the contents of an HTML application has been published page or to provide a REST response such as in the Tracking service at /Tracking/Orders. This should be easy, but a feature of the EclipseLink library called JPA-RS will try to register itself to handle REST requests, and if discovered by the Jersey provider it will take over that root URL! There are ways in which to tell Jersey to scan only certain packages, but there are (a) non-portable, and (b) unworkable in a couple of cases, because they in turn make it impossible for a component to dig its way back to the application subclass. So after whacking at this four or five different ways I decided that to go with manual publishing in most services would make for the cleanest and simplest experience in lab exercises, with as few tool-specific distractions as possible. 6

7 Chapter 3 We re covering JAX-RS mechanisms for completeness here, and it s not a bad thing for students to ease into JAX-RS. Especially, those who know web application development will find things like query and form parameters to be familiar ground. But only a few slices of what we cover in these chapters are parts of typical, modern service implementations. I suggest that you cover this material, in full, take the labs, etc., but maybe hit some parts harder (path parameters, headers, query parameters) and point out others as more esoteric (matrix parameters, form parameters, cookies). Remind students that HTTP entities are the biggest and best conduit for information in most cases, and that they ll be moving in that direction soon. You might want to point out some more subtle differences between the use of path, query, and matrix parameters as compared to other options. Only the path parameter can be used to affect selection of a sub-resource method or locator; all the others relate only to the consumption of request content. But, query and matrix parameters can trigger HTTP 404s when they are unparseable, where other parsing failures are reported as 400s. The idea is that query and matrix values are part of the top line of the HTTP request, and that a missing value can be seen as a failure to address a resource even if in JAX-RS this occurs at a later stage. On the flip side, you might prefer to direct requests to different methods based on the presence of query parameters and, sadly, JAX-RS doesn t support that. The CarLot example is intended as a focused study of the JAX-RS heuristic for finding subresource methods and locators; it is not a good example of REST style, especially in the DELETE method with /Delete in the URL. 7

8 Chapter 6 In this chapter I try to cover a number of alternatives for one of the most important parts of any REST architecture, which is a standard means by which to pass complex business data back and forth. I try to illuminate the pros and cons of XML-vs.-JSON, JAXB-vs.-not, but not to be too preachy about one approach or another. You may well have your own take on this, and it s also possible that the group you re teaching will already have committed to one approach or another. It should be easy enough to focus on one piece and to de-emphasize others. In fact the main case study for this chapter and for most CRUD-pattern material the rest of the way is implemented in dual, and, while we do shade a bit towards JSON with MOXy, this chapters labs and several later ones can be pursued in either a JAXB or a non- JAXB mode, with full starter and answer code throughout. Chapter 9 One shortcoming of the course s exercises generally is that we don t illustrate the proper use of the Location header when responding with HTTP 201. This is probably the time during the course at which to mention this, and describe the better practice as supported by JAX- RS: use Response.create and pass the location of the created resource, or add the header yourself if already doing lower-level work with the HTTP response. A limitation of inheriting JAX-RS annotations and overriding sub-resource methods won t be apparent in this chapter s exercises but will start to show up in the sub-resources chapter: you can t override a method in order to expand its semantics, for example by offering additional query parameters. This is where injectable fields really shine, though, as you can define a field for a query parameter that may be relevant in a subclass, and then check it from an override of a base-class method. The later lab in the Insurance service is an example of this. Chapter 11 The sub-resource framework shown in this chapter should appeal to students at this stage of the course, now that we ve seen some of the challenges of supporting CRUD patterns generically and have databases on which to set larger systems of resources. One limitation, which you may want to discuss, is the error handling. There are a number of opportunities for simple NullPointerExceptions to crash request processing, especially in sub-resource locators, and these should be tested more carefully and turned into HTTP 404s. 8

9 Chapter 12 It never seemed quite worth mentioning in the coursebook proper, but the lab software does include the HTTPSniffer tool that we use in a number of other courses. There might be other parts of the course where it would be useful but especially in this chapter, if students either are having trouble with the client lab exercise or just are curious about the HTTP that clients are sending, you can point them to this tool. Usage is very simple, just run cc.http.httpsniffer as a Java application, from Eclipse or the command line, and direct clients to port 8079 instead of The tool will pass all traffic and will log it to the console and to a file Traffic.txt. Chapter 15 This is by no means a comprehensive treatment of security practices for REST. It s just meant to offer an overview and show a little bit of working code. Consider our Course 562 for in-depth treatment of such topic areas as HMAC techniques, SAML, and OAuth. 9

10 Revision History Version covers a broader scope of topics, while still working with JAX-RS 2.0. Major changes include: There is a new chapter on REST sub-resources and JAX-RS support for them via sub-resource locators. There is a new chapter on testing strategies, with a focus on the Jersey test framework. We have dropped the separate material on JAXB, though this can be added back on a custom basis. Version 2.0 brings the course forward to Java EE 7 and JAX-RS 2.0. Major changes from the 1.1 version are: We ve dropped the big technology-neutral overview of SOAP and REST at the beginning. We just get down to cases with REST in the first chapter now. There is a new Chapter 2 that includes previous material on configuration but also focuses on component lifecycle. Entity translation is a much bigger part of the course now. We ve taken what was a single, fast-paced tour of the Billing service in the final chapter, and stretched it out to a multi-step case study so that we can consider some of the key concepts one at a time and with more hands-on exercises. More bite-size pieces: CRUD, XML, JSON, JAXB, error handling and validation, use of generics, working with JPA. JAXB is still in a separate one-chapter module, but we don t line it up to be covered in full prior to JAX-RS as before. See the comments in the Timeline section of this guide. There are new chapters on dependency injection, error handling and validation, generics, working with JPA, client API, filters and interceptors, and security. Version 1.1 is the initial release of the course, for Java EE 6 and JAX-RS

11 Troubleshooting If you run into any trouble with code exercises, the first and best thing to do is to doublecheck that the classroom machines have been set up precisely according to the course setup guide. Especially, the wrong version of a tool can cause significant problems; don t wander off-book in this way unless absolutely sure you can support the software that you prefer and that we haven t tested. Check environment variable settings carefully, too; these are the cause of a great many classroom glitches. Below are some specific pitfalls that have come up in previous offerings of the course: Be certain you have taken the few steps indicated in the Tools and Environment pages in the first chapter of the coursebook, such as editing the SetEnvironment script and certain workspace settings to fit any non-standard locations on student machines. 11

12 Errata The following issues were discovered after the most recent release, and will be addressed on the next maintenance cycle: [Nothing yet!] Feedback We very much appreciate whatever feedback we can get on our courseware especially from the instructor s perspective. Naturally, the more specific, the better, and we strongly encourage you to make notes on issues you may encounter in the classroom, whether they re typos, missing files, or suggestions for clearer language to explain a concept. We can t guarantee that we ll act on every suggestion, but we re aggressive about stamping out problems and try to be highly responsive. Hopefully this means that when you give us good feedback, you get a better course the next time you need to teach it. Please direct all courseware feedback to Will Provost Capstone Courseware mailto:provost@capcourse.com For anyone who s interested, we have a very informal defect-tracking system, based in Excel spreadsheets with columns to capture defect location, nature, status, and author feedback. Ultimately, feedback goes into these sheets, so if you want a template, we ll be happy to provide one, to facilitate the reporting process. 12

Developing RESTful Services in Java

Developing RESTful Services in Java Version 1.1 Instructor s Guide Overview We begin this course, as we do all our Java web services courses these days, with a twochapter overview of web services and the