Start of REST documentation

spring-framework-reference/src/rest.xml

+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter>
+  <title>Spring REST support </title>
+
+  <section>
+    <title>Introduction</title>
+
+    <para>The goal of Spring's REST support is to make the development of
+    'RESTful' Web services and applications easier. Client-side access to
+    RESTful resources is greatly simplified using Spring
+    <classname>RestTemplate</classname>. <classname>RestTemplate</classname>
+    follows in the footsteps of other 'Template' classes in Spring such as
+    <classname>JdbcTemplate</classname> and
+    <classname>JmsTemplate</classname>. Instead of dealing with a verbose
+    lower level API such as Apache Commons HttpClient to create RESTful
+    request, RestTemplate provides one liner methods that are purpose built
+    for RESTful programming. On the server-side, Spring's REST support is
+    based upon Spring's existing annotation based MVC framework. (For those
+    interested in the rational for that decision, and say not implenting
+    JAX-RS, read Arjen Putsma's SpringSource TeamBlog <ulink
+    url="http://blog.springsource.com/2009/03/08/rest-in-spring-3-mvc/">entry</ulink>.)
+    With little effort, you can marshall data out of a RESTful request using
+    @RequestMapping and @PathVariable annotations and return different views
+    as determined by the request's Context-Type header. </para>
+
+    <para>In this chapter we describe all the features of Spring's REST
+    support. It is divided into two main two chapters, one for the server-side
+    and one for the client-side. For those new to Spring's <link
+    linkend="mvc">MVC framework</link>, you may want to read through the
+    reference documentation on <link linkend="mvc-annotation">annotation-based
+    controller configuration</link> to undestand the general programming
+    model. </para>
+  </section>
+
+  <section>
+    <title>Creating RESTful services</title>
+
+    <para>Spring's annotation-based MVC framework serves as the basis for
+    creating RESTful Web Services. As such, you configure your servlet
+    container as you would for a Spring MVC application using Spring's <link
+    linkend="mvc-servlet">DispatcherServlet</link>. </para>
+
+    <section>
+      <title>URI templates</title>
+
+      <para>RESTful services use URIs to name resourses. To faciliate
+      accessing the information contained in a URI, its structure follows
+      conventions so that it can easily be described in a parameterized form.
+      The <ulink url="http://bitworking.org/projects/URI-Templates/">proposed
+      RFC</ulink> for URI Templates defines how a URI is parameterized. For
+      example, the URI Template</para>
+
+      <programlisting>http://www.example.com/users/{userid}</programlisting>
+
+      <para>contains the variable 'userid'. If we assign the variable the
+      value "fred", then 'expanding' the URI Template gives.</para>
+
+      <programlisting>http://www.example.com/users/fred</programlisting>
+
+      <para>When processing an request the URI can be compared to an expected
+      URI Template in order to extract a collection of variables. </para>
+
+      <para>Spring uses the <classname>@RequestMapping</classname> annotation
+      to define the URI Template for the request.
+      The<classname>@PathVariable</classname> annotation is used to extract
+      the value of the template variables and assign their value to a method
+      variable. A Spring controller method to process above example is shown
+      below;</para>
+
+      <programlisting language="java">@RequestMapping("/users/{userid}", method=RequestMethod.GET)
+public String getUser(@PathVariable String userId) {
+  // implementation omitted...
+}</programlisting>
+
+      <para>The request <literal>http://www.example.com/users/fred</literal>
+      will bind the userId method parameter to the String value 'fred'.
+      </para>
+
+      <section id="path-variable">
+        <title>Mapping RESTful URLs with the @PathVariable annotation</title>
+
+        <para>The <classname>@PathVariable</classname> method level annotation
+        is used to indicate that a method parameter should be bound to the
+        value of a URI template variable. </para>
+
+        <para>The following code snippet shows the use of a single
+        <classname>@PathVariable</classname> in a controller method:</para>
+
+        <programlisting language="java">@RequestMapping("/owners/{ownerId}", method=RequestMethod.GET)
+public String findOwner(<emphasis role="bold">@PathVariable</emphasis> String ownerId, Model model) {
+  Owner owner = ownerService.findOwner(ownerId);  
+  model.addAttribute("owner", owner);  
+  return "displayOwner"; 
+}
+</programlisting>
+
+        <para>The URI Template "<literal>/owners/{ownerId}</literal>"
+        specifies the variable name ownerId. When the controller handles this
+        request, the value of ownerId is set the the value in the request URI.
+        For example, when a request comes in for /owners/fred, the value
+        'fred' is bound to the method parameter <literal>String
+        ownerId</literal>. </para>
+
+        <para>The matching of method parameter names to URI Template variable
+        names can only be done if your code is compiled with debugging
+        enabled. If you do have not debugging enabled, you must specify the
+        name of the URI Template variable name to bind to in the @PathVariable
+        annotation. For example</para>
+
+        <programlisting>@RequestMapping("/owners/{ownerId}", method=RequestMethod.GET)
+public String findOwner(<emphasis role="bold">@PathVariable</emphasis>("ownerId") String ownerId, Model model) {
+  // implementation omitted
+}
+</programlisting>
+
+        <para>The name of the method parameter does not matter in this case,
+        so you may also use create a controlled method with the signature
+        shown below</para>
+
+        <programlisting>@RequestMapping("/owners/{ownerId}", method=RequestMethod.GET)
+public String findOwner(<emphasis role="bold">@PathVariable</emphasis>("ownerId") String theOwner, Model model) {
+  // implementation omitted
+}</programlisting>
+
+        <para>Multiple @PathVariable annotations can be used to bind to
+        multiple URI Template variables as shown below:</para>
+
+        <programlisting language="java">@RequestMapping("/owners/{ownerId}/pets/{petId}", method=RequestMethod.GET)
+public String findPet(<emphasis role="bold">@PathVariable</emphasis> String ownerId, <emphasis
+            role="bold">@PathVariable</emphasis> String petId, Model model) {
+  Owner owner = ownerService.findOwner(ownderId);  
+  Pet pet = owner.getPet(petId);  
+  model.addAttribute("pet", pet);  
+  return "displayPet"; 
+}
+</programlisting>
+
+        <para>The following code snippet shows the use of path variables on a
+        relative path</para>
+
+        <programlisting language="java">@Controller
+@RequestMapping(<emphasis role="bold">"/owners/{ownerId}/**"</emphasis>)
+public class RelativePathUriTemplateController {
+
+  @RequestMapping(<emphasis role="bold">"/pets/{petId}"</emphasis>)
+  public void findPet(@PathVariable String ownerId, @PathVariable String petId, Model model) {    
+    // implementation omitted
+  }
+}
+</programlisting>
+
+        <tip>
+          <para>method parameters that are decorated with the
+          <interfacename>@PathVariable</interfacename> annotation can be of
+          <emphasis role="bold">any simple type </emphasis>such as int, long,
+          Date... Spring automatically converts to the appropriate type and
+          throws a <classname>TypeMismatchException</classname> if the type is
+          not correct.</para>
+        </tip>
+      </section>
+    </section>
+
+    <section>
+      <title>Content Negotiation</title>
+
+      <para>blah blah</para>
+    </section>
+
+    <section>
+      <title>Views</title>
+
+      <para>blah</para>
+    </section>
+
+    <section>
+      <title>HTTP Method Conversion</title>
+
+      <para>blah blah</para>
+    </section>
+
+    <section>
+      <title>ETag support</title>
+
+      <para>blah blah</para>
+    </section>
+
+    <section>
+      <title>Exception Handling</title>
+
+      <para>@ExceptionHandler</para>
+    </section>
+  </section>
+
+  <section>
+    <title>Accessing RESTful services on the Client</title>
+
+    <para>Spring provides a client-side API blah blah</para>
+
+    <section>
+      <title>RestTemplate</title>
+
+      <para>blah blah</para>
+    </section>
+
+    <section>
+      <title>HTTP Message Conversion</title>
+
+      <para>blah blah</para>
+
+      <section>
+        <title>StringHttpMessageConverter</title>
+
+        <para></para>
+
+        <para></para>
+      </section>
+
+      <section>
+        <title>FormHttpMessageConverter</title>
+
+        <para></para>
+
+        <para></para>
+      </section>
+
+      <section>
+        <title>ByteArrayMessageConverter</title>
+
+        <para></para>
+
+        <para></para>
+      </section>
+
+      <section>
+        <title>MarshallingHttpMessageConverter</title>
+
+        <para></para>
+
+        <para></para>
+      </section>
+
+      <section>
+        <title>SourceHttpMessageConverter</title>
+
+        <para></para>
+      </section>
+    </section>
+  </section>
+</chapter>
\ No newline at end of file