[exo-jcr-commits] exo-jcr SVN: r2888 - jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws.
do-not-reply at jboss.org
do-not-reply at jboss.org
Thu Aug 5 10:50:44 EDT 2010
Author: dkatayev
Date: 2010-08-05 10:50:43 -0400 (Thu, 05 Aug 2010)
New Revision: 2888
Added:
jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/introduction-to-rest.xml
Log:
EXOJCR-870 WS introduction chapter (introduction-to-rest.xml) reverted
Added: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/introduction-to-rest.xml
===================================================================
--- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/introduction-to-rest.xml (rev 0)
+++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/ws/introduction-to-rest.xml 2010-08-05 14:50:43 UTC (rev 2888)
@@ -0,0 +1,212 @@
+<?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 id = "WS.Introduction">
+ <?dbhtml filename="ch-introduction-to-rest.html"?>
+
+ <title>Introduction to the Representational State Transfer (REST)</title>
+
+ <section>
+ <title>Introduction</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>
+
+ <para><command>Note</command>: RESTful architecture is not limited to
+ those methods, one of good examples of extension is the WebDAV
+ protocol.</para>
+
+ <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>
+</chapter>
More information about the exo-jcr-commits
mailing list