You are previewing REST in Practice.

REST in Practice

Cover of REST in Practice by Ian Robinson... Published by O'Reilly Media, Inc.
  1. REST in Practice
    1. SPECIAL OFFER: Upgrade this ebook with O’Reilly
    2. Foreword
    3. Preface
      1. Should I Read This Book?
      2. Should I Skip This Book?
      3. Resources
      4. What Did You Think About the Book?
      5. Errata
      6. Conventions Used in This Book
      7. Using Code Examples
      8. How to Contact Us
      9. Safari® Books Online
      10. Acknowledgments
    4. 1. The Web As a Platform for Building Distributed Systems
      1. Architecture of the Web
      2. Thinking in Resources
      3. From the Web Architecture to the REST Architectural Style
      4. The Web As an Application Platform
      5. Web Friendliness and the Richardson Maturity Model
      6. GET on Board
    5. 2. Introducing Restbucks: How to GET a Coffee, Web Style
      1. Restbucks: A Little Coffee Shop with Global Ambitions
      2. Toolbox
      3. Here Comes the Web
    6. 3. Basic Web Integration
      1. Lose Weight, Feel Great!
      2. A Simple Coffee Ordering System
      3. URI Templates
      4. URI Tunneling
      5. POX: Plain Old XML over HTTP
      6. We Are Just Getting Started
    7. 4. CRUD Web Services
      1. Modeling Orders As Resources
      2. Building CRUD Services
      3. Aligning Resource State
      4. Consuming CRUD Services
      5. Consuming Services Automatically with WADL
      6. CRUD Is Good, but It’s Not Great
    8. 5. Hypermedia Services
      1. The Hypermedia Tenet
      2. Hypermedia Formats
      3. Contracts
      4. Hypermedia Protocols
      5. Implementing a Hypermedia Service
      6. Building the Ordering Service in Java
      7. Building the Ordering Service in .NET
      8. Ready, Set, Action
    9. 6. Scaling Out
      1. GET Back to Basics
      2. Caching
      3. Making Content Cacheable
      4. Implementing Caching in .NET
      5. Consistency
      6. Extending Freshness
      7. Stay Fresh
    10. 7. The Atom Syndication Format
      1. The Format
      2. Common Uses for Atom
      3. Using Atom for Event-Driven Systems
      4. Building an Atom Service in Java
      5. Building an Atom Service in .NET
      6. Atom Everywhere?
      7. After the Event
    11. 8. Atom Publishing Protocol
      1. Atom Publishing Protocol
      2. Implementing Order Fulfillment Using AtomPub
      3. Implementing AtomPub in .NET
      4. A Versatile Protocol
    12. 9. Web Security
      1. HTTP Security Essentials
      2. Identity and the OpenID Protocol
      3. The OAuth Protocol
      4. Service Hacks and Defenses
      5. Final Thoughts
    13. 10. Semantics
      1. Syntax Versus Semantics
      2. Structure and Representation of Information
      3. The Semantic Web
      4. Microformats
      5. Linked Data and the Web
      6. Guidance
    14. 11. The Web and WS-*
      1. Are Web Services Evil?
      2. SOAP: The Whole Truth
      3. WSDL: Just Another Object IDL
      4. Two Wrongs Don’t Make a Right
      5. Secure, Reliable, Transacted
      6. A Requiem for Web Services?
    15. 12. Building the Case for the Web
      1. No More Silver Bullets
      2. Building and Running Web-Based Services
      3. No Architecture Without Measurement
      4. Selling the Web
      5. Go Forth and Build
    16. Index
    17. About the Authors
    18. Colophon
    19. SPECIAL OFFER: Upgrade this ebook with O’Reilly

Consuming Services Automatically with WADL

Although the patterns for writing clients in .NET and Java are easy to understand and implement, we can save ourselves effort—and, in some cases, generate code automatically—using service metadata. Up to this point, much of the work we’ve done in building our ordering service and its consumers has been plumbing code. But for some kinds of services,[37] a static description can be used to advertise the addresses and representation formats of the resources the service hosts. This is the premise of the Web Application Description Language, or WADL.

A WADL contract is an XML document that describes a set of resources with URI templates, permitted operations, and request-response representations. As you’d expect, WADL also supports the HTTP fault model and supports the description of multiple formats for resource representations. Example 4-34 shows a WADL description of the Restbucks ordering service.

Example 4-34. Ordering service WADL example

<?xml version="1.0" encoding="utf-8"?>

    <include href="order.xsd"/>

  <resources base="">
    <resource path="order">
      <method name="POST">
          <representation mediaType="application/xml" element="ord:order"/>

          <representation status="201"/>
          <fault mediaType="application/xml" element="ord:error" status="400"/>
          <fault mediaType="application/xml" element="ord:error" status="500"/>
    <resource path="order/{orderId}">
      <method name="GET">
          <representation mediaType="application/xml" element="ord:order"/>
          <fault mediaType="application/xml" element="ord:error" status="404"/>
          <fault mediaType="application/xml" element="ord:error" status="500"/>
      <method name="PUT">
          <representation mediaType="application/xml" element="ord:order"/>
          <representation status="200"/>
          <fault mediaType="application/xml" element="ord:error" status="404"/>
          <fault mediaType="application/xml" element="ord:error" status="409"/>
          <fault mediaType="application/xml" element="ord:error" status="500"/>
      <method name="DELETE">
          <representation status="200"/>
          <fault mediaType="application/xml" element="ord:error" status="404"/>
          <fault mediaType="application/xml" element="ord:error" status="405"/>
          <fault mediaType="application/xml" element="ord:error" status="500"/>

The <application> element is the root for the WADL metadata. It acts as the container for schemas that describe the service’s resource representations in the <grammars> element and the resources that are contained within the <resources> element. The <grammars> element typically refers to XML Schema schemas (which we have defaulted to for Restbucks) that describe the structure of the resource representations supported by the service, though other schema types (e.g., RELAX NG) are supported too. Consumers of the service can use this information to create local representations of those resources such as orders and products.

In a WADL description, the <resources> element is where most of the action happens. It provides a static view of the resources available for consumption. It uses a templating scheme that allows consumers to infer the URIs of the resources supported by a service. Calculating URIs can be a little tricky since WADL relies on a hierarchy of resources, with each URI based on the parent URI’s template plus its own. In Example 4-34, we have two logical resources: for POST and{orderId} for the other verbs. The resource URIs are computed by appending the path of the <resource> element to the path defined in the base attribute of the <resources> element.


In addition to dealing with URI templates and query strings, WADL also has a comprehensive mechanism for building URIs. WADL can deal with form encoding and handling a range of URI structures, including matrix URIs.[38]

The <method> element allows WADL to bring together the request and response resource representations and HTTP verbs to describe the set of permissible interactions supported by the service. The Restbucks ordering service is described in terms of two separate resource paths. We first define the order resource (<resource path=“order”>), which only allows POST requests (<method name=“POST”>) and requires that the payload of those requests be XML representations of an order. We also describe the possible ways the Restbucks ordering service can reply to a POST request (in the <response> element) depending on the outcome of processing the submitted order. In this case, the possible response code is 201, 400, or 500.

Using a URI template, a second set of resources—the orders that Restbucks has created—is advertised by the element <resource path=“order/{orderId}”>. Like the POST method element, each subsequent <method> element describes the possible responses and faults that the ordering service might return. Additionally, the PUT <method> element declares that an XML order representation must be present as the payload of any PUT requests.

While it’s helpful that we can read and write WADL by hand (at least in simple cases), the point of WADL is to help tooling automate as much service plumbing as possible. To illustrate how WADL can be consumed by an automation infrastructure, the authors of WADL have created the WADL2Java[39] tool.[40] WADL2Java allows us to create consumer-side Java that minimizes the code we have to write in order to interact with a service described in WADL. The Java code in Examples Example 4-35 and Example 4-36 shows the consumer-side API that Java programmers can use to interact with a WADL-decorated ordering service.

Example 4-35. WADL-generated endpoint

public class Endpoint {
  public static class Orders {

    public DataSource postAsIndex(DataSource input)
       throws IOException, MalformedURLException {
      // Implementation removed for brevity

  public static class OrdersOrderId {

    public OrdersOrderId(String orderid)
        throws JAXBException {
      // Implementation removed for brevity

    // Getters and setters omitted for brevity

    public DataSource getAsApplicationXml()
      throws IOException, MalformedURLException {
      // Implementation removed for brevity

    public Order getAsOrder()
      throws ErrorException, IOException, MalformedURLException, JAXBException {
      // Implementation removed for brevity

    public DataSource putAsIndex(DataSource input)
      throws IOException, MalformedURLException {
      // Implementation removed for brevity

    public DataSource deleteAsIndex()
      throws IOException, MalformedURLException {
      // Implementation removed for brevity

In Java, resources are locally represented by classes such as Order, shown in Example 4-36, which allow us to inspect and set values in the XML representations exchanged with the ordering service.

Example 4-36. Java representation of an order resource

@XmlType(name = "", propOrder = {
@XmlRootElement(name = "order")
public class Order {

    @XmlElement(required = true)
    protected String location;
    @XmlElement(required = true)
    protected Order.Items items;
    @XmlElement(required = true)
    protected String status;

    // Getters and setters only, omitted for brevity


WADL can be useful as a description language for CRUD services such as the ordering service. It can be used to automatically generate plumbing code with very little effort, compared to manually building clients. Since the client and server collaborate over the life cycle of a resource, its URI, and its representation format, it does not matter whether the plumbing is generated from a metadata description. Indeed, WADL descriptions may help expedite consumer-side maintenance when changes happen on the server side.


As we will see in the next chapter, the Web uses hypermedia to provide contracts in a much more loosely coupled way than WADL. But for CRUD-only services, WADL can be a useful tool.

[37] CRUD services are great candidates for describing with WADL. Hypermedia services—as we will see in the next chapter—use different mechanisms to describe the protocols they support.

[40] Other tools also exist; for example, REST Describe at

The best content for your career. Discover unlimited learning on demand for around $1/day.