Loading ...
Sorry, an error occurred while loading the content.

[ZapFlash] Shoehorning Java into RESTful Design

Expand Messages
  • Gervas Douglas
    Shoehorning Java into RESTful Design Document ID: | Document Type: ZapFlash By: /Leonid Felikson/ | Posted: /November 1, 2012/ What are the primary reasons you
    Message 1 of 1 , Nov 1, 2012
    • 0 Attachment

      Shoehorning Java into RESTful Design

      Document ID: | Document Type: ZapFlash
      By: Leonid Felikson | Posted: November 1, 2012

      What are the primary reasons you code in Java in your enterprise IT shop? Be honest now:

      a) We have solid Java programming skills on staff

      b) We have a lot of existing Java in production we’ve coded over the years and/or we’ve made a significant investment in Java-centric infrastructure (ESBs, application servers, etc.)

      c) Of all the languages and programming and execution environments we could have chosen, Java is the best suited for addressing our specific bespoke software challenges, independent of current skill sets, infrastructure, or existing production code.

      If you selected a and/or b but not c, then you have what we like to call a legacy Java problem. There are other, perhaps more modern languages that would better suit your needs, but because of your existing investments in people and technology, you’ve essentially shoehorned Java.

      All is not lost, however. The ongoing efforts of the Java Community Process (JCP) have augmented the capabilities of the Java ecosystem in order to tackle a wide range of new problems and situations. This ongoing work on Java may continue to meet your needs for years into the future.

      But then again, maybe not. The heavyweight model-view-controller (MVC) architecture of Java EE, or simply the object-oriented context of Java more broadly may not support alternative architectural approaches. In particular, if you are building a distributed hypermedia application, then a RESTful architectural approach will likely better meet your needs than a Java-centric architectural approach.

      JAX-RS to the Rescue?

      But wait, you Java geeks out there are saying, can’t we have both? Wouldn’t it be ideal if we had a Java-centric way of building RESTful applications? After all, the JCP has worked to address Java’s support for REST, which led them to the Java APIs for RESTful Services (JAX-RS) standard. Now we can build RESTful applications simply and easily in Java, right?

      Unfortunately, JAX-RS is a classic example of shoehorning. It adds some RESTful capabilities to Java, but fights the RESTful architectural style every step of the way. Case in point: the Hypermedia as the Engine of Application State (HATEOAS) constraint. JAX-RS 1.1 didn’t support hypermedia at all, which essentially meant that we would have to simulate HATEOAS characteristics by utilizing core Java capabilities. To make JAX-RS fully RESTful, you would have to design applications that satisfied all of REST’s architecture constraints, compensating for those features that did not have adequate support during development. JAX-RS 1.1 provides adequate support for satisfying some REST architecture constraints, but punts on HATEOAS.

      JAX-RS is an adequate API for implementing RESTful Services in Java, but JAX-RS version 1.1 has no built-in support for hypermedia. In JAX-RS 2.0, expands hypermedia support. The JCP has added hyperlinks and client support to the forthcoming JAX-RS 2.0, but even so, developers will find JAX-RS an immature tool for building distributed hypermedia systems.

      More Challenges with JAX-RS

      To simplify the development and deployment of RESTful Services, JAX-RS uses Java annotations. There are Java annotations to express REST resources, media types, access methods, etc. There are no annotations to express hyperlinks. You have to design those yourself.

      As another example, consider standardized Service contract and loose coupling design principles. RESTful Service contracts require the unification and standardization of the resource identifier syntax and conventions for expressing and accessing resources. In the case of RESTful Services, you should design URIs in a consistent way. Furthermore, URIs should be opaque to reduce coupling between consumers and RESTful services. JAX-RS allows such consistency, but doesn’t encourage or enforce it.

      It’s also important to standardize custom media types whenever possible, and you must also select which standard media types and custom media types you should use. Furthermore, the Service discoverability design principle requires having hypermedia controls in place, based on the REST HATEOAS design constraint. Discoverability provides a way of making the protocol self-documenting. JAX-RS doesn’t help with either of these design principles.

      As a final example of shoehorning, consider the two different types of links that JAX-RS defines: transitional links which describe optional next actions and structural links which provide optional detailed information. Transitional links tell a client where to proceed next, while structural links help to shorten representations in order to avoid aggregate data. Details are replaced by links. Transitional links have some support in JAX-RS 2.0, but structural links are not supported due to their level of complexity.

      So, why have structural links in the first place? The answer: we’re trying to shoehorn the Java object structure into hypermedia. If we simply take a Java object and convert it into hypermedia, we end up with links that represent all the various method calls on the associated object instances, resulting in excessively large, complex representations. Instead, JAX-RS encourages transitional links which enable the client to drill down to the underlying aggregate data. But if we weren’t handcuffed by the Java object structure in the first place, we’d never bother with transitional and structural links. Instead, we’d design our hypermedia applications to support discoverability. In other words, a core Java pattern becomes a hypermedia antipattern.

      The ZapThink Take

      It’s quite common for developers to rush to developing Services without first understanding the design of their final product. It is especially important when we are developing RESTful Services to have a well-architected, comprehensive design for developing Services that follow RESTful architectural constraints. However, to develop a good RESTful Service takes more than a good development tool or coding best practices accumulated over time.

      People are often confused while developing with JAX-RS and thinking REST. JAX-RS is not REST design; rather, JAX-RS should support good RESTful design. Furthermore, the use of JAX-RS API does not lead to the creation of fully RESTful Services unless you have completed proper RESTful design beforehand. The design has to ensure that you have satisfied all RESTful architecture constraints.

      Finally, established SOA governance should include policies and processes related to the endorsement of RESTful architecture principles. Those policies should cover design requirements and policies that you have established for satisfying RESTful design principles. But without adequate architecture, all the coding in the world won’t lead to proper governance.

    Your message has been successfully submitted and would be delivered to recipients shortly.