<?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">
<section id="WS.Introduction">
  <title>Introduction to the Representational State Transfer (REST)</title>

    <para><command>Representational State Transfer (REST)</command> is a style
    of software architecture for distributed hypermedia systems such as the
    World Wide Web. The term was introduced in the doctoral dissertation in
    2000 by Roy Fielding, one of the principal authors of the Hypertext
    Transfer Protocol (HTTP) specification, and has come into widespread use
    in the networking community.</para>

    <para>REST strictly refers to a collection of network architecture
    principles that outline how resources are defined and addressed. The term
    is often used in a looser sense to describe any simple interface that
    transmits domain-specific data over HTTP without an additional messaging
    layer such as SOAP or session tracking via HTTP cookies.</para>

    <para>The key abstraction of information in REST is a
    <command>resource</command>. Any information that can be named can be a
    resource: a document or image, a temporal service (e.g. "today's weather
    in Los Angeles"), a collection of other resources, a non-virtual object
    (e.g. a person), and so on. In other words, any concept that might be the
    target of an author's hypertext reference must fit within the definition
    of a resource. A resource is a conceptual mapping to a set of entities,
    not the entity that corresponds to the mapping at any particular point in
    time.</para>

    <para>REST uses a <command>resource identifier </command>to identify the
    particular resource involved in an interaction between components. REST
    connectors provide a generic interface for accessing and manipulating the
    value set of a resource, regardless of how the membership function is
    defined or the type of software that is handling the request. URL or URN
    are the examples of a resource identifier.</para>

    <para>REST components perform actions with a resource by using a
    <command>representation</command> to capture the current or intended state
    of that resource and transferring that representation between components.
    A representation is a sequence of bytes, plus <command>representation
    metadata </command>to describe those bytes. Other commonly used but less
    precise names for a representation include: <command>document, file, and
    HTTP message entity, instance, or variant</command>. A representation
    consists of data, metadata describing the data, and, on occasion, metadata
    to describe the metadata (usually for the purpose of verifying message
    integrity). Metadata are in the form of name-value pairs, where the name
    corresponds to a standard that defines the value's structure and
    semantics. The data format of a representation is known as a media
    type.</para>

    <table>
      <title>REST Data Elements</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry align="center">Data Element</entry>

            <entry align="center">Modern Web Examples</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>resource</entry>

            <entry>the intended conceptual target of a hypertext
            reference</entry>
          </row>

          <row>
            <entry>resource identifier</entry>

            <entry>URL, URN</entry>
          </row>

          <row>
            <entry>representation</entry>

            <entry>HTML document, JPEG image</entry>
          </row>

          <row>
            <entry>representation metadata</entry>

            <entry>media type, last-modified time</entry>
          </row>

          <row>
            <entry>resource metadata</entry>

            <entry>source link, alternates, vary</entry>
          </row>

          <row>
            <entry>control data</entry>

            <entry>if-modified-since, cache-control</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <para>REST uses various <command>connector</command> types to encapsulate
    the activities of accessing resources and transferring resource
    representations. The connectors present an abstract interface for
    component communication, enhancing simplicity by providing a complete
    separation of concepts and hiding the underlying implementation of
    resources and communication mechanisms.</para>

    <table>
      <title>REST Connectors</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry align="center">Connector</entry>

            <entry align="center">Modern Web Examples</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>client</entry>

            <entry>libwww, libwww-perl</entry>
          </row>

          <row>
            <entry>server</entry>

            <entry>libwww, Apache API, NSAPI</entry>
          </row>

          <row>
            <entry>cache</entry>

            <entry>browser cache, Akamai cache network</entry>
          </row>

          <row>
            <entry>resolver</entry>

            <entry>bind (DNS lookup library)</entry>
          </row>

          <row>
            <entry>tunnel</entry>

            <entry><para></para>SOCKS, SSL after HTTP CONNECT</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <para>The primary connector types are client and server. The essential
    difference between the two is that a client initiates communication by
    making a request, whereas a server listens for connections and responds to
    requests in order to supply access to its services. A component may
    include both client and server connectors.</para>

    <para>An important part of RESTful architecture is a well-defined
    interface to communicate, in particular it is a set of HTTP methods such
    as POST, GET, PUT and DELETE. These methods are often compared with the
    CREATE, READ, UPDATE, DELETE (CRUD) operations associated with database
    technologies. An analogy can also be made:</para>

    <itemizedlist>
      <listitem>
        <para>PUT is analogous to CREATE or PASTE OVER,</para>
      </listitem>

      <listitem>
        <para>GET to READ or COPY,</para>
      </listitem>

      <listitem>
        <para>POST to UPDATE or PASTE AFTER, and</para>
      </listitem>

      <listitem>
        <para>DELETE to DELETE or CUT.</para>
      </listitem>
    </itemizedlist>

    <note><para>RESTful architecture is not limited to
    those methods, one of good examples of extension is the WebDAV
    protocol.</para></note>

    <para>The <command>CRUD</command> (Create, Read, Update and Delete) verbs
    are designed to operate with atomic data within the context of a database
    transaction. REST is designed around the atomic transfer of a more complex
    state and can be viewed as a mechanism for transferring structured
    information from one application to another.</para>

    <para>HTTP separates the notions of a web server and a web browser. This
    allows the implementation of each to vary from the other based on the
    client/server principle. When used RESTfully, HTTP is
    <command>stateless</command>. Each message contains all the information
    necessary to understand the request.</para>

    <para>As a result, neither the client nor the server needs to remember any
    communication-state between messages. Any state retained by the server
    must be modeled as a resource.</para>
</section>
