One document matched: draft-griffin-bliss-rest-00.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc toc='yes'?>
<?rfc tocdepth='5'?>
<?rfc compact='yes'?>
<?rfc subcompact='no'?>
<?rfc symrefs="yes"?>
<rfc category="info" ipr="full3978">
<front>
<title abbrev="REST for BLISS">Representational State Transfer (REST) for Feature Configuration in Session Initiation Protocol (SIP)</title>
<author fullname="Keith Griffin" initials="K.G." surname="Griffin">
<organization>Cisco</organization>
<address>
<postal>
<city>Oranmore Business Park</city>
<region>Galway</region>
<country>Ireland</country>
</postal>
<email>kegriffi@cisco.com</email>
</address>
</author>
<author fullname="Jonathan Rosenberg" initials="J.R." surname="Rosenberg">
<organization>Cisco</organization>
<address>
<postal>
<city>Iselin</city>
<region>NJ</region>
<country>US</country>
</postal>
<email>jdrosen@cisco.com</email>
<uri>http://www.jdrosen.net</uri>
</address>
</author>
<date year="2008" />
<area>RAI</area>
<workgroup>BLISS</workgroup>
<keyword>process</keyword>
<abstract>
<t>In order to provide interoperable implementations of certain
Session Initiation Protocol (SIP) based features, such as
automated call handling, it is necessary for devices to
configure network servers with feature data. An example is a
call forwarding number for a call forwarding service. This
document introduces the concept of Representational State
Transfer (REST) and gives an example of how REST can be used
for such configuration.</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>
The Session Initiation Protocol (SIP) <xref target="RFC3261"/> can be
used to realize numerous communications features. These include basic
telephony functions, such as call hold, transfer, and automated call
handling. However, in practice, there has been limited
interoperability for many of these advanced features. The BLISS
working group has been chartered to improve this interoperability
<xref target="I-D.ietf-bliss-problem-statement"/>. One of the current
areas of study is automated call handling (ACH)
<xref target="I-D.ietf-bliss-ach-analysis"/>. ACH includes features
like call forwarding, forward to voicemail, and do-not-disturb, all of
which involve an automated decision on treatment of a call based on
some kind of condition.
</t>
<t>
In order to achieve interoperability for ACH types of features, it is
necessary to have a common mechanism by which endpoints - such as hard
phones and soft clients - can configure data required for operation of
those features. As a simple example, when a user presses the 'call
forward all' button on their phone, this needs to cause a change in
call handling configuration on their server. That configuration
information - whether call forwarding is enabled or not - is then used
by the server when receiving an incoming call.
</t>
<t>
This document introduces the concept of Representational State
Transfer (REST) as a potential solution to this
problem. It gives an example of an existing web service using REST,
and shows some example REST exchanges
for configuration of call forwarding. This document is not meant as a
concrete proposal for specific REST schemas, but rather, to facilitate
discussion around the concept.
</t>
</section>
<section anchor="sec-overview" title="Overview of REST">
<t>
Representational State Transfer or REST is an architectural style for
networked systems as described in Dr. Roy Fieldings Ph.D. dissertation
<xref target="Fielding-PHD"/>. It is not dependant upon any particular
protocol. This means that
it is possible to create a REST based system that is not built upon
HTTP. However, most practical implementations of REST are built on
HTTP. REST is not a standard however it does prescribe the use of
standards, including but not limited to:
</t>
<list style="symbols">
<t>HTTP</t>
<t>URL</t>
<t>XML, HTML, GIF, JPEG (representations of resources)</t>
<t>TEXT/XML, TEXT/HTML, IMAGE/GIF, IMAGE/JPEG (content types)
</t>
</list>
<section title="Design Principles of a REST Based System">
<list style="hanging">
<t hangText="Stateless:"> Every request from client to server must
contain all the information required to execute the request and must
not rely on information known to the server. </t>
<t hangText="Uniform interface"> to support state transfer consisting
of:
<list style="symbols">
<t>A constrained set of well defined operations e.g. the HTTP methods
GET, PUT, POST, DELETE.</t>
<t>A constrained set of content types e.g. text/xml, image/jpeg.</t>
</list></t>
<t hangText="Client server pull interaction:"> consuming clients pull
representations.</t>
<t hangText="Uniquely Named Resources:"> A URI is used to name the
resources which comprise the system. </t>
<t hangText="Layered">, interconnected resource representations:
resource representations are interconnected using
URLs enabling a client to progress through states. </t>
<t hangText="Cacheable"> responses to promote network efficiency. </t>
</list>
<t>
An important principle of
REST is that of resources. A resource is a source of specific
information which is named by a URI. Resources are manipulated by
network components using a uniform interface e.g. HTTP. Resulting
state changes for the resource are returned as representations
e.g. XML document. As REST interfaces are by definition highly
connected via URI, deeply linked representations are typically used
over wide or shallow representations. This means that a representation
returns specifically the data that it represents but is tightly linked
to related data that an application might be interested in.
</t>
</section>
<section title="Advantages and Disadvantages of a REST Based
Architecture">
<t>
There are
several advantages and disadvantages to REST based
architectures. Indeed in Chapter 5 of the previously referenced
doctoral dissertation from Dr Roy Fielding, many of these are
described and discussed. What follows are some of the more commonly
perceived advantages and disadvantages associated with REST.
</t>
<section title="REST Advantages">
<list style="symbols">
<t>Offers possibilities for thin client development as less client
code is required. </t>
<t>Does not require explicit resource discovery mechanism due to
hyperlinking. </t>
<t> Scalable architecture compared with those that require stateful
servers. </t>
<t> Caching promotes
network efficiency and fast response times. </t>
<t> Software versioning
benefits including support of document type evolution such as HTML and
XML without impacting backward or forward compatibility.
</t>
<t>Resource extensibility, allowing support for new content types without
impacting existing and legacy content types.
</t>
</list>
</section>
<section title="REST Disadvantages">
<list style="symbols">
<t>HTTP as a uniform interface presents technical challenges for real
time asynchronous events to a thin client or browser based
application.</t>
<t>Managing URI Namespace can be cumbersome.</t>
<t>Lacks supporting software tools </t>
<t>Can impact network performance by
encouraging more frequent client-server requests and responses.</t>
</list>
</section>
</section>
<section title="REST Architecture">
<t><xref target="fig-rest-arch"/> shows an architecture for client-server
communications based on REST. It can be seen that the uniform
interface is presented by HTTP and the resource representations are
shared over this interface. The REST aware client code shown is
typically part of a web page that is loaded from a web
server. JavaScript is commonly used as a client side language embedded
in HTML to manipulate resources. Where data is returned it is parsed
and acted upon by this client side code based on the logic of the
application. Later we will see how the interface is defined with
operations in the uniform interface (HTTP) with resources represented
as URIs. The architecture also shows how several underlying standards
such as HTTP, URL, HTML and XML can be used to support a REST based
architecture.
</t>
<figure title="REST Architecture" anchor="fig-rest-arch"><artwork>
<![CDATA[
HTTP Method
GET, POST, PUT DELETE
REST Payload
Representation with URI
+------------------+ +------------------+
| +-------+ | | +-------+ |
| HTTP | REST | | -----------------------> | | REST | |
|Client |Aware | | | |Aware | |
| | Client| | | |Server | HTTP |
| | Code | | | | Code | Server |
| | | | | | | |
| | | | <----------------------- | | | |
| +-------+ | | +-------+ |
+------------------+ HTTP Response +------------------+
REST XML Return Data
]]></artwork></figure>
<t>It is useful to map the HTTP methods to database CRUD operations. The
mapping is quit straightforward:</t>
<figure><artwork>
<![CDATA[
HTTP Method CRUD Operation
----------- --------------
POST Create
GET Read
PUT Update
DELETE Delete
]]></artwork></figure>
</section>
</section>
<section title="Existing REST Example">
<t>
This section provides a brief example of an existing REST-based API
used in the Web.
</t>
<t>The API at http://apidoc.digg.com/ListStories is used
by the Digg web application, to allow a client to retrieve stories
about a particular topic. An example to retrieve three most recent
stories about Apple:
</t>
<figure><artwork>
<![CDATA[
http://services.digg.com/stories/topic/apple?count=3
&appkey=http%3A%2F%2Fexample.com%2fapplication
]]></artwork></figure>
<t>
Would produce the following example response:
</t>
<figure><artwork>
<![CDATA[
<?xml version="1.0" encoding="utf-8" ?>
<stories timestamp="1196894147" min_date="1194302130" total="2636"
offset="0" count="3">
<story id="4368401" link="http://maxsangalli.altervista.org/?p=45"
submit_date="1196891534" diggs="1" comments="0" status="upcoming"
media="news" href="http://digg.com/linux_unix/Jukebox_con_Linux">
<title>Jukebox con Linux</title>
<description>Jukebox with Linux</description>
<user name="ilsanga" icon="http://digg.com/img/udl.png"
registered="1196891377" profileviews="0" />
<topic name="Linux/Unix" short_name="linux_unix" />
<container name="Technology" short_name="technology" />
<thumbnail originalwidth="390" originalheight="387"
contentType="image/jpeg"
src="http://digg.com/linux_unix/Jukebox_con_Linux/t.jpg" width="80"
height="80" />
</story>
<story id="4367880"
link="http://www.itsyourip.com/ip-tools/arping-ping-using-address-resolution-protocolarp/"
submit_date="1196888736" diggs="2" comments="0" status="upcoming"
media="news"
href="http://digg.com/linux_unix/ARPing_Ping_using_Address_Resolution_Protocol_ARP">
<title>ARPing - Ping using Address Resolution Protocol(ARP)</title>
<description>ARPing is an utility that can be used to ping using
Address Resolution Protocol (ARP) requests instead of using Internet
Control Message Protocol (ICMP) as used in standard Ping
utility. ARPing can be used for Duplicate Address Detection
(DAD)</description>
<user name="rbkumaran" icon="http://digg.com/users/rbkumaran/l.png"
registered="1151050300" profileviews="42" />
<topic name="Linux/Unix" short_name="linux_unix" />
<container name="Technology" short_name="technology" />
</story>
<story id="4367579"
link="http://linuxdevices.com/news/NS9372729455.html"
submit_date="1196887377" diggs="5" comments="0" status="upcoming"
media="news"
href="http://digg.com/linux_unix/EMF_changes_tune_hails_embedded_Linux">
<title>EMF changes tune, hails embedded Linux </title>
<description>Embedded Market Forecasters has issued a report
claiming that embedded Linux is as dependable as other real time
operating systems (RTOSs). The independently funded report appears
to recant EMF's controversial Microsoft-funded report in 2003 that
claimed that embedded Windows OSes were far faster and cheaper than
embedded Linux. ...</description>
<user name="gadgeek" icon="http://digg.com/img/udl.png"
registered="1131035306" profileviews="1717" />
<topic name="Linux/Unix" short_name="linux_unix" />
<container name="Technology" short_name="technology" />
<thumbnail originalwidth="125" originalheight="76"
contentType="image/gif"
src="http://digg.com/linux_unix/EMF_changes_tune_hails_embedded_Linux/t.gif"
width="80" height="80" />
</story>
]]></artwork></figure>
<t>
In general, the HTTP URI is structured to provide different data
depending on the fields present. As an example:
</t>
<figure><artwork>
<![CDATA[
GET /stories
All stories.
GET /stories/popular
Popular stories.
GET /stories/upcoming
Upcoming stories.
GET /stories/top
Top stories.
GET /stories/hot
Hot stories.
GET /stories/container/{container name}
All stories from a given container.
404 Not Found if the container does not exist.
GET /stories/container/{container name}/popular
Popular stories from a given container.
404 Not Found if the container does not exist.
GET /stories/container/{container name}/upcoming
Upcoming stories from a given container.
404 Not Found if the container does not exist.
GET /stories/container/{container name}/top
Top stories from a given container.
404 Not Found if the container does not exist.
]]></artwork></figure>
<t>
See how the natural structure of the URI itself provides a
hierarchical view on the data, and how URI parameters are used to
represent parameters of queries.
</t>
</section>
<section title="Example REST API for Call Forwarding">
<t>
Based on this simple model, the following is a view on how one might
define a REST API for setting a call forward no-answer service.
</t>
<t>
To set CFNA:
</t>
<figure><artwork>
<![CDATA[
PUT systemusers/bob/cfna HTTP/1.1
<?xml version="1.0"?>
<cfna>enable</cfna>
]]></artwork></figure>
<t>To get current CFNA state:</t>
<figure><artwork>
<![CDATA[
GET systemsusers/bob/cfna HTTP/1.1
]]></artwork></figure>
<t>Would return:
</t>
<figure><artwork>
<![CDATA[
HTTP/1.1 200 OK
<?xml version="1.0" ?>
<cfna>enabled</cfna>
]]></artwork></figure>
<t>
It is also possible to define a model for setting CFNA on a
line-by-line basis, rather than per user. In that case, the URI would
be structured as device/line/CFA. In the case of a device called
"BobsPhone" and line 4622:
</t>
<figure><artwork>
<![CDATA[
PUT BobsPhone/4622/cfna HTTP/1.1
<?xml version="1.0"?>
<cfna>enable</cfna>
]]></artwork></figure>
</section>
<section title="Security Considerations">
<t>
There are no security considerations associated with this
specification.
</t>
</section>
</middle>
<back>
<references title="Informational References">
<?rfc include='reference.RFC.3261'?>
<?rfc include='reference.I-D.ietf-bliss-problem-statement'?>
<?rfc include='reference.I-D.ietf-bliss-ach-analysis'?>
<reference anchor="Fielding-PHD">
<front>
<title>
Architectural Styles and the Design of Network-based Software Architectures
</title>
<author initials="R" surname="Fielding" fullname="Roy Fielding">
<organization/>
</author>
<date year="2000"/>
</front>
<seriesInfo name="Doctoral" value="Dissertation"/>
<format type="HTML" target="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm"/>
</reference>
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 05:29:16 |