< draft-ietf-simple-xcap-00.txt   draft-ietf-simple-xcap-01.txt >
SIMPLE J. Rosenberg SIMPLE J. Rosenberg
Internet-Draft dynamicsoft Internet-Draft dynamicsoft
Expires: December 22, 2003 June 23, 2003 Expires: April 26, 2004 October 27, 2003
The Extensible Markup Language (XML) Configuration Access Protocol The Extensible Markup Language (XML) Configuration Access Protocol
(XCAP) (XCAP)
draft-ietf-simple-xcap-00 draft-ietf-simple-xcap-01
Status of this Memo Status of this Memo
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that other Task Force (IETF), its areas, and its working groups. Note that other
groups may also distribute working documents as Internet-Drafts. groups may also distribute working documents as Internet-Drafts.
skipping to change at page 1, line 31 skipping to change at page 1, line 31
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at http:// The list of current Internet-Drafts can be accessed at http://
www.ietf.org/ietf/1id-abstracts.txt. www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on December 22, 2003. This Internet-Draft will expire on April 26, 2004.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2003). All Rights Reserved. Copyright (C) The Internet Society (2003). All Rights Reserved.
Abstract Abstract
This specification defines the Extensible Markup Language (XML) This specification defines the Extensible Markup Language (XML)
Configuration Access Protocol (XCAP). XCAP allows a client to read, Configuration Access Protocol (XCAP). XCAP allows a client to read,
write and modify application configuration data, stored in XML format write and modify application configuration data, stored in XML format
skipping to change at page 2, line 14 skipping to change at page 2, line 14
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Overview of Operation . . . . . . . . . . . . . . . . . . . 4 2. Overview of Operation . . . . . . . . . . . . . . . . . . . 4
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . 5
4. Application Usages . . . . . . . . . . . . . . . . . . . . . 6 4. Application Usages . . . . . . . . . . . . . . . . . . . . . 6
5. URI Construction . . . . . . . . . . . . . . . . . . . . . . 8 5. URI Construction . . . . . . . . . . . . . . . . . . . . . . 8
5.1 Identifying the XML Document . . . . . . . . . . . . . . . . 8 5.1 Identifying the XML Document . . . . . . . . . . . . . . . . 8
5.2 Identifying the XML Nodes . . . . . . . . . . . . . . . . . 9 5.2 Identifying the XML Nodes . . . . . . . . . . . . . . . . . 9
6. Client Operations . . . . . . . . . . . . . . . . . . . . . 10 6. Client Operations . . . . . . . . . . . . . . . . . . . . . 12
6.1 Creating a New Document . . . . . . . . . . . . . . . . . . 10 6.1 Creating a New Document . . . . . . . . . . . . . . . . . . 12
6.2 Replace an Existing Document . . . . . . . . . . . . . . . . 10 6.2 Replace an Existing Document . . . . . . . . . . . . . . . . 12
6.3 Deleting a Document . . . . . . . . . . . . . . . . . . . . 10 6.3 Deleting a Document . . . . . . . . . . . . . . . . . . . . 12
6.4 Fetching a Document . . . . . . . . . . . . . . . . . . . . 10 6.4 Fetching a Document . . . . . . . . . . . . . . . . . . . . 12
6.5 Creating a New Element . . . . . . . . . . . . . . . . . . . 10 6.5 Creating a New Element . . . . . . . . . . . . . . . . . . . 12
6.6 Replacing an Element in the Document . . . . . . . . . . . . 11 6.6 Replacing an Element in the Document . . . . . . . . . . . . 13
6.7 Delete an Element . . . . . . . . . . . . . . . . . . . . . 12 6.7 Delete an Element . . . . . . . . . . . . . . . . . . . . . 13
6.8 Fetch an Element . . . . . . . . . . . . . . . . . . . . . . 12 6.8 Fetch an Element . . . . . . . . . . . . . . . . . . . . . . 13
6.9 Create an Attribute . . . . . . . . . . . . . . . . . . . . 12 6.9 Create an Attribute . . . . . . . . . . . . . . . . . . . . 14
6.10 Replacing Attributes . . . . . . . . . . . . . . . . . . . . 13 6.10 Replacing Attributes . . . . . . . . . . . . . . . . . . . . 14
6.11 Deleting Attributes . . . . . . . . . . . . . . . . . . . . 13 6.11 Deleting Attributes . . . . . . . . . . . . . . . . . . . . 14
6.12 Fetching Attributes . . . . . . . . . . . . . . . . . . . . 13 6.12 Fetching Attributes . . . . . . . . . . . . . . . . . . . . 14
6.13 Fetching Metadata . . . . . . . . . . . . . . . . . . . . . 13 6.13 Read/Modify/Write Transactions . . . . . . . . . . . . . . . 15
6.14 Read/Modify/Write Transactions . . . . . . . . . . . . . . . 14 7. Server Behavior . . . . . . . . . . . . . . . . . . . . . . 16
7. Server Behavior . . . . . . . . . . . . . . . . . . . . . . 15
7.1 POST Handling . . . . . . . . . . . . . . . . . . . . . . . 16 7.1 POST Handling . . . . . . . . . . . . . . . . . . . . . . . 16
7.2 PUT Handling . . . . . . . . . . . . . . . . . . . . . . . . 17 7.2 PUT Handling . . . . . . . . . . . . . . . . . . . . . . . . 17
7.3 GET Handling . . . . . . . . . . . . . . . . . . . . . . . . 18 7.3 GET Handling . . . . . . . . . . . . . . . . . . . . . . . . 18
7.4 DELETE Handling . . . . . . . . . . . . . . . . . . . . . . 18 7.4 DELETE Handling . . . . . . . . . . . . . . . . . . . . . . 18
7.5 Managing Modification Times . . . . . . . . . . . . . . . . 19 7.5 Managing Etags . . . . . . . . . . . . . . . . . . . . . . . 19
8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 21 8. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 20
9. Security Considerations . . . . . . . . . . . . . . . . . . 23 9. Security Considerations . . . . . . . . . . . . . . . . . . 23
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 24 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . 24
Normative References . . . . . . . . . . . . . . . . . . . . 25 Normative References . . . . . . . . . . . . . . . . . . . . 25
Informative References . . . . . . . . . . . . . . . . . . . 26 Informative References . . . . . . . . . . . . . . . . . . . 26
Author's Address . . . . . . . . . . . . . . . . . . . . . . 27 Author's Address . . . . . . . . . . . . . . . . . . . . . . 27
Intellectual Property and Copyright Statements . . . . . . . 28 Intellectual Property and Copyright Statements . . . . . . . 28
1. Introduction 1. Introduction
The Session Initiation Protocol for Instant Messaging and Presence In many communications applications, such as Voice over IP, instant
Leveraging Extensions (SIMPLE) working group has been developing messaging, and presence, it is necessary for network servers to
specifications for subscribing to, and receiving notifications of, access per-user information in the process of servicing a request.
user presence [10]. An important aspect of user presence is This per-user information resides within the network, but is managed
authorization policy. Indeed, the presence specification requires a by the end user themselves. Its management can be done through a
Presence Agent (PA) to both authenticate and authorize all multiplicity of access points, including the web, a wireless handset,
subscriptions before accepting them. However, it does not define how or a PC application.
the server determines the authorization status of a subscriber. Users
can set their authorization policy through web pages or voice
response systems. However, there is currently no protocol specified
for setting this policy. A protocol for this purpose is called an
authorization manipulation protocol.
Mechanisms have also been defined to support reactive authorization
[11][12]. Reactive authorization allows the user to be informed when
someone has attempted to subscribe to their presence when the server
is unable to determine an authorization policy. The user can then go
and set an authorization policy for the subscriber, using the same
unspecified mechanism for setting the policy.
Another important aspect of presence systems is the buddy list, also
known as the presence list. This is a list of users that a watcher
wishes to learn presence state for. This list can be stored in the
client, or it can be stored in a centralized server. In the latter
case, the client would subscribe to the list as a whole [13]. The
presence list can be set by using a web page or voice response
application. However, there is no protocol mechanism currently
specified to manage the presence list. Such a protocol is called a
presence list manipulation protocol.
The SIMPLE group has defined requirements for an authorization Examples of per-user information are presence [12] authorization
manipulation protocol and a presence list manipulation protocol. policy and presence lists. Presence lists are lists of users whose
These protocols have similar requirements, and are captured in [14]. presence is desired by a watcher. Presence information for the list
of users can be obtained by subscribing to a resource which
represents that list [15]. In this case, the Resource List Server
(RLS) requires access to this list in order to process a SIP
[11]SUBSCRIBE [20] request for it. Requirements for manipulation of
presence lists and authorization policies have been specified by the
SIMPLE working group [16].
This document proposes a candidate for the authorization and presence This specification describes a protocol that can be used to
manipulation protocol, called the Extensible Markup Language (XML) manipulate this per-user data. It is called the Extensible Markup
Configuration Access Protocol (XCAP). XCAP is not actually a new Language (XML) Configuration Access Protocol (XCAP). XCAP is not a
protocol. XCAP is a set of conventions for using HTTP to read, write new protocol. Rather, it is a set of conventions for mapping XML
and modify XML configuration data. XCAP is based heavily on ideas documents and document components into HTTP URIs, rules for how the
modification of one resource affects another, data validation
constraints, and authorization policies associated with access to
those resources. Because of this structure, normal HTTP primitives
can be used to manipulate the data. XCAP is based heavily on ideas
borrowed from the Application Configuration Access Protocol (ACAP) borrowed from the Application Configuration Access Protocol (ACAP)
[15], but it is not an extension of it, nor does it have any [18], but it is not an extension of it, nor does it have any
dependencies on it. Like ACAP, XCAP is meant to support the dependencies on it. Like ACAP, XCAP is meant to support the
configuration needs for a multiplicity of applications, rather than configuration needs for a multiplicity of applications, rather than
just a single one. just a single one.
2. Overview of Operation 2. Overview of Operation
XCAP supports the needs of any application that needs access to data Each application that makes use of XCAP specifies an application
defined by clients of the application. Each application that makes usage (Section 4). This application usage defines the XML schema [1]
use of XCAP specifies an application usage (Section 4). This for the data used by the application, along with other key pieces of
application usage defines the XML schema [1] for the data used by the information. The principal task of XCAP is to allow clients to read,
application, along with other key pieces of information. The write, modify, create and delete pieces of that data. These
principal task of XCAP is to allow clients to read, write, modify, operations are supported using HTTP 1.1 [2]. An XCAP server acts as a
create and delete pieces of that data. These operations are supported repository for collections of XML documents. There will be documents
using HTTP 1.1 [2]. An XCAP server acts as a repository for stored for each application. Within each application, there are
collections of XML documents. There will be documents stored for each documents stored for each user. Each user can have a multiplicity of
application. Within each application, there are documents stored for documents for a particular application. To access some component of
each user. Each user can have a multiplicity of documents for a one of those documents, XCAP defines an algorithm for constructing a
particular application. To access some component of one of those URI that can be used to reference that component. Components refer to
documents, XCAP defines an algorithm for constructing a URI that can any subtree of the document, or any attribute for any element within
be used to reference that component. Components refer to any subtree the document. Thus, the HTTP URIs used by XCAP point to pieces of
of the document, or any attribute for any element within the
document. Thus, the HTTP URIs used by XCAP point to pieces of
information that are finer grained than the XML document itself. information that are finer grained than the XML document itself.
With a standardized naming convention for components of XML With a standardized naming convention for mapping components of XML
documents, the basic operations for accessing the data are simple. documents to HTTP URIs, the basic operations for accessing the data
Reading one of the components is just a standard HTTP GET operation. are provided by existing HTTP primitives. Reading one of the
Writing, creating or modifying one of the components is a standard components is accomplished with HTTP GET, creating or modifying one
HTTP POST or PUT operation. Deleting a component is just a standard of the components is done with an HTTP PUT, and removing one of the
DELETE operation. For example, to add a friend to a presence list, a components is done with an HTTP DELETE. To provide atomic read/
client would construct an XML document fragment which contains the modify/write operations, HTTP entity tags are used.
information on that friend. The client would then construct a URI
that refers to the location in the presence list document where this
new fragment is to be added. The client then performs a POST
operation against the URI, placing the document fragment into the
body of the POST request. To provide atomic read/modify/write
operations, the HTTP If-Unmodified-Since header field is used. The
HTTP POST operation used by the client would contain the date
obtained in the Last-Modified header field from the GET used to read
the data.
3. Terminology 3. Terminology
In this document, the key words "MUST", "MUST NOT", "REQUIRED", In this document, the key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" are to be interpreted as described in RFC 2119 [3] and and "OPTIONAL" are to be interpreted as described in RFC 2119 [3] and
indicate requirement levels for compliant implementations. indicate requirement levels for compliant implementations.
4. Application Usages 4. Application Usages
A central concept in XCAP is that of an application usage. An A central concept in XCAP is that of an application usage. An
application usage defines the way in which a specific application application usage defines the way in which a specific application
makes use of XCAP. This definition is composed of several pieces of makes use of XCAP. This definition is composed of several pieces of
information, such as an XML schema and constraints on values of one information, such as an XML schema and constraints on values of one
element given values in another. element given values in another.
Application usages are documented in specifications which convey this Application usages are documented in specifications which convey this
information. In particular, an application usage specification MUST information. In particular, an application usage specification MUST
provide the following information: provide the following information:
Application Usage ID (AUID): Each application usage is associated Application Usage ID (AUID): Each application usage is associated
with a name, called an AUID. This name uniquely identifies the with a name, called an AUID. This name uniquely identifies the
application usage, and is different from all other AUIDs. AUIDs application usage, and is different from all other AUIDs. AUIDs
exist in one of two namespaces. The first namespace is the IETF exist in one of two namespaces. The first namespace is the IETF
namespace. This namespace contains a set of tokens, each of which namespace. This namespace contains a set of tokens, each of which
is registered with IANA. These registrations occur with the is registered with IANA. These registrations occur with the
publication of standards track RFCs [16] based on the guidelines publication of standards track RFCs [19] based on the guidelines
in Section 10. The second namespace is the vendor-proprietary in Section 10. The second namespace is the vendor-proprietary
namespace. Each AUID in that namespace is prefixed with the token namespace. Each AUID in that namespace is prefixed with the
"vnd", followed by a period ("."), followed by a valid DNS name, reverse domain name name of the organization creating the AUID,
followed by another period, followed by any vendor defined token. followed by a period, followed by any vendor defined token. As an
A vendor creating such an AUID MUST only create one using domain example, the example.com domain can create an AUID with the value
names for which it is an administrator. As an example, the "com.example.foo" but cannot create one with the value
example.com domain can create an AUID with the value "org.example.foo". AUIDs within the vendor namespace do not need
"vnd.example.com.foo" but cannot create one with the value to be registered with IANA. The vendor namespace is also meant to
"vnd.example.org.bar". AUIDs within the vendor namespace do not be used in lab environments where no central registry is needed.
need to be registered with IANA. The vendor namespace is also The syntax for AUIDs, expressed in ABNF [7] (and using some of the
meant to be used in lab environments where no central registry is BNF defined in RFC 2396 [8]) is:
needed.
MIME Type: Each application usage MUST register a MIME type for AUID = global-auid / vendor-auid
its XML documents. This is done based on the procedures of RFC global-auid = auid
3023 [4]. auid = alphanum / mark
vendor-auid = rev-hostname "." auid
rev-hostname = toplabel *( "." domainlabel )
domainlabel = alphanum
/ alphanum *( alphanum / "-" ) alphanum
toplabel = ALPHA / ALPHA *( alphanum / "-" ) alphanum
XML Schema: Each application will have a unique schema which MIME Type: Each application usage MUST register a MIME type for its
defines the data needed by the application. In XCAP, this schema XML documents. This is done based on the procedures of RFC 3023
is represented using XML schema. As an example, presence list data [4].
is composed of a list of URIs, each of which represends a member
of presence list. [17] defines the XML schema for this data.
Additional Constraints: XML schemas can represent a variety of XML Schema: Each application will have a unique schema which defines
the data needed by the application. In XCAP, this schema is
represented using XML schema [1].
Additional Constraints: XML schemas can represent a variety of
constraints about data, such as ranges and types. However, schemas constraints about data, such as ranges and types. However, schemas
cannot cover all types of data constraints, including constraints cannot cover all types of data constraints, including constraints
introduced by data interdependencies. For example, one XML element introduced by data interdependencies. For example, one XML element
may contain an integer which defines the maximum number of may contain an integer which defines the maximum number of
instances of another element. The application usage defines these instances of another element. The application usage defines these
additional constraints. additional constraints.
Data Semantics: The application usage needs to define detailed Data Semantics: The application usage needs to define detailed
semantics for each piece of data in the schema. semantics for each piece of data in the schema.
Naming Conventions: The data defined by the XML schema will be Naming Conventions: The data defined by the XML schema will be used
used by any number of entities participating in the application. by any number of entities participating in the application. In the
In the case of presence list, the data is used by the Resource case of presence list, the data is used by the Resource List
List Server (RLS), which reads the data, and by the clients, which Server (RLS), which reads the data, and by the clients, which
write it. During the execution of the application (i.e., the write it. During the execution of the application (i.e., the
processing of the list subscription), specific documents will need processing of the list subscription), specific documents will need
to be read or written. In order for the application to function to be read or written. In order for the application to function
properly, there needs to be agreement on exactly which documents properly, there needs to be agreement on exactly which documents
are read or written by the application. This is an issue of naming are read or written by the application. This is an issue of naming
conventions; agreeing on how an application constructs the URI conventions; agreeing on how an application constructs the URI
representing the document that is to be read or written. The representing the document that is to be read or written. The
application usage spells out this information. application usage spells out this information.
Computed Data: Frequently, some of the data defined in the schema Resource Interdependencies: In many cases, when a user modifies an
is not independent; that is, its value depends on the values of XCAP resource, many other resources need to change as well. Such
other elements in the document. As a result, when a client uses interdependencies are application usage dependent. As an example,
XCAP to modify the independent pieces of the document, the server when a user performs a PUT operation to create a new presence
needs to compute the dependent ones in order to fully populate the list, the server may need to fill in the URI associated with that
document. The application usage needs to define which data list. These interdependencies need to be specified by the
components are dependent, and how they are computed. As an application usage. Note that, if a server needs to modify data
example, when the URI for a presence list is not specified by a within a document just PUT by the client, this modification is
client, a URI is chosen by the server and filled in. This needs to effectively accomplished as a separate transaction. Concretely,
be specified by the application usage. this means that, after the server modifies the data, the entity
tags are updated as if the client had made the change itself.
Authorization Policies: By default, an XCAP server will only allow Authorization Policies: By default, an XCAP server will only allow a
a user to access (read, write, delete or modify) their own user to access (read, write, delete or modify) their own
documents. The application usage can specify differing default documents. The application usage can specify differing default
authorization policies. Of course, the default can always be authorization policies. An application usage can also specify
overriden by operator or user-specified policies. whether another application usage is used to define the
authorization policies. An application usage for setting
authorization policies can also be defined subsequent to the
definition of the the main application usage. In such a case, the
main application usage needs only to specify that such a usage
will be defined in the future.
Application usages are similar to dataset classes in ACAP. Application usages are similar to dataset classes in ACAP.
5. URI Construction 5. URI Construction
In order to manipulate a piece of configuration data, the data must In order to manipulate a piece of configuration data, the data must
be represented by an HTTP URI. XCAP defines a specific naming be represented by an HTTP URI. XCAP defines a specific naming
convention for constructing these URIs. This convention is very convention for constructing these URIs. In particular, the host part
similar to the naming conventions used for dataset classes in ACAP, identifies the XCAP server. The abs_path component of the HTTP URI
and makes use the XPath [5] specification for identifying nodes of an identifies the specific XML document to be modified. XCAP servers
XML document. organize XML documents in a specific hierarchical fashion, as
described in Section 5.1. The URI MAY contain a query. This query is
The HTTP URI consists of two parts: called a node selector. When present, it contains an XML component
identifier formatted according to Section 5.2. The node selector
XCAP-URI = Document-URI ["?" Node-Selector] identifies the specific component of the XML document. The HTTP URI
Document-URI = http_URL ;from RFC2616 without the query is called the document URI. , and makes use the
Node-Selector = *uric ;Escape coded LocationPath from XPath specification for identifying nodes of an XML document.
The first part, the Document-URI, selects a specific XML document. It
is a valid HTTP URL, subject to the constraints described here. The
constraints for constructing this URI are discussed below in Section
5.1. Once a document is selected, the remainder of the URI (the
Node-Selector) identifies which components of the document are being
addressed. The Node-Selector is an XPath [5] LocationPath expression,
subject to constraints described below.
5.1 Identifying the XML Document 5.1 Identifying the XML Document
XCAP mandates that a server organizes documents according to a XCAP mandates that a server organizes documents according to a
defined hierarchy. The root of this hierarchy is an HTTP URI called defined hierarchy. The root of this hierarchy is an HTTP URI called
the XCAP services root URI. This URI identifies the root of the tree the XCAP services root URI. This URI identifies the root of the tree
within the domain where all XCAP documents are stored. It can be any within the domain where all XCAP documents are stored. It can be any
valid HTTP URL, but MUST NOT contain a query string. As an example, valid HTTP URL, but MUST NOT contain a query string. As an example,
http://xcap.example.com/services might be used as the XCAP services http://xcap.example.com/services might be used as the XCAP services
root URI within the example.com domain. Typically, the XCAP services root URI within the example.com domain. Typically, the XCAP services
skipping to change at page 8, line 50 skipping to change at page 8, line 42
Beneath the XCAP services root URI is a tree structure for organizing Beneath the XCAP services root URI is a tree structure for organizing
documents. The first level of this tree consists of the XCAP AUID. documents. The first level of this tree consists of the XCAP AUID.
So, continuing the example above, all of the documents used by the So, continuing the example above, all of the documents used by the
presence list application would be under http://xcap.example.com/ presence list application would be under http://xcap.example.com/
services/presence-lists. services/presence-lists.
It is assumed that each application will have data that is set by It is assumed that each application will have data that is set by
users, and/or it will have global data that applies to all users. As users, and/or it will have global data that applies to all users. As
a result, within the directory structure for each application usage, a result, within the directory structure for each application usage,
there are two sub-trees. One, called "users", holds the documents there are two sub-trees. One, called "users", holds the documents
that are applicable to only specific users, and the other, called that are applicable to specific users, and the other, called
"global", holds documents applicable to all users. "global", holds documents applicable to all users.
Within the "users" tree are zero or more sub-trees, each of which Within the "users" tree are zero or more sub-trees, each of which
identifies a documents that apply to a specific user. XCAP does not identifies a documents that apply to a specific user. XCAP does not
itself define what it means for documents to "apply" to a user, itself define what it means for documents to "apply" to a user,
beyond specification of a baseline authorization policy. beyond specification of a baseline authorization policy.
Specifically, the default authorization policy is that only a user Specifically, the default authorization policy is that only a user
who authenticates themself as user X can read, write, or otherwise who authenticates themself as user X can read, write, or otherwise
access in any way the documents within sub-tree X. Each application access in any way the documents within sub-tree X. Each application
usage can specify additional authorization policies which depend on usage can specify additional authorization policies which depend on
data used by the application itself. data used by the application itself.
The remainder of the URI (the path following "global" or the specific The remainder of the URI (the path following "global" or the specific
user) is not constrained by this specification. The application usage user) is not constrained by this specification. The application usage
MAY introduce constraints, or may allow any structure to be used. MAY introduce constraints, or may allow any structure to be used.
5.2 Identifying the XML Nodes 5.2 Identifying the XML Nodes
The second component of the XCAP URI specifies specific nodes of the The second component of the XCAP URI specifies specific nodes of the
XML document which are to be accessed. Nodes, in this context, refers XML document which are to be accessed. A node refers to either an XML
to the definition provided in the XPath specification, and therefore element or an attribute of an element. The node selector is an
includes XML elements, attributes, text, namespaces, processing expression which identifies an element or attribute. Its grammar is:
instructions, comments, and roots. These nodes are identified by a
LocationPath expression, as defined in XPath. Either the abbreviated
or unabbreviated form MAY be used.
Contraints are imposed on the XPath expression based on the operation node-selector = element-selector ["/" attribute-selector]
being performed. These do not constrain the functions or axes that element-selector = step *( "/" step)
can be used in the XPath expression, but rather constrain the step = by-name / by-pos / by-attr
resulting node set. See Section 6 for details. by-name = QName ; from XML Namespaces
by-pos = QName "[" position "]"
position = 1*DIGIT
by-attr = QName "[" "@" att-name "=" <">
att-value <"> "]"
att-name = QName
att-value = AttValue ; from XML specification
by-pos = QName "[" position "]"
position = *DIGIT
attribute-selector = "@" att-name
The node selector is based on the concepts in XPath [5]. Indeed, the
node selector expression happens to be a valid XPath expression.
However, XPath provides a set of functionality far richer than is
needed here, and its breadth would introduce complexity into XCAP.
To determne the XML element or attribute selected by the node
selector, processing begins at the root of the XML document. The
first step in the element selector is then taken. Each step chooses a
specific XML element within the current document context. The
document context is the point within the XML document from which a
specific step is evaluated. The document context begins at the root
of the document. When a step determines an element within that
context, that element becomes the new context for evaluation of the
next step. Each step can select an element by its name, by a
combination of name and attribute value, or by name and position. If
the step is attempting selection by name, the server looks for all
elements within the current context with that name. Name matching is
performed as described below. If there is more than one element with
the specified name, the result is considered a no-match.
If the step is attempting selection by name and attribute, the server
looks for all elements within the current document context with that
name. Of those that match, it looks for ones that have the given
attribute name, where that attribute has the given value. If there is
no match, or if more than one element matches, the result is
considered a no-match.
If the step is attempting selection by name and position, the server
looks for all elements within the current document context with that
name. These are then sorted in document order, as defined by Xpath.
The position-th element is then selected. If there are fewer than
position number of elements with that name, the result is considered
a no-match.
Once the last step is executed, if there is no attribute selector,
the result of the node selection is the last selected element. If
there is an attribute selector, the server checks to see if there is
an attribute with that name within the currently selectoed element.
If there is not, the result is considered a no-match. Otherwise, that
attribute is selected.
Matching of element names and attributes is performed by expanding
them into the expanded name form, as described in XML Namespaces, and
then performing the comparison of the results. When evaluating the
QNames in the node selector, the default namespace and namespace
definitions from the document URI apply.
As an example, consider the following XML document:
<?xml version="1.0"?>
<watcherinfo xmlns="urn:ietf:params:xml:ns:watcherinfo"
version="0" state="full">
<watcher-list resource="sip:professor@example.net" package="presence">
<watcher status="active"
id="8ajksjda7s"
duration-subscribed="509"
event="approved" >sip:userA@example.net</watcher>
<watcher status="pending"
id="hh8juja87s997-ass7"
display-name="Mr. Subscriber"
event="subscribe">sip:userB@example.org</watcher>
</watcher-list>
</watcherinfo>
The node selector "watcherinfo/watcher-list/
watcher[@id="8ajksjda7s"]" would select the following XML element:
<watcher status="active"
id="8ajksjda7s"
duration-subscribed="509"
event="approved" >sip:userA@example.net</watcher>
6. Client Operations 6. Client Operations
An XCAP client is an HTTP 1.1 compliant client. An XCAP client An XCAP client is an HTTP 1.1 compliant client. Specific data
performs a set of primitive operations by invoking specific methods manipulation tasks are accomplished by invoking the right set of HTTP
against the server, using specific URIs, where the requests contain methods with the right set of headers on the server. This section
bodies and headers subject to specific constraints. The set of describes those in detail
primitive operations, the methods used to accomplish them, and the
header and body constraints are described here.
6.1 Creating a New Document 6.1 Creating a New Document
To create a new document, the client constructs a URI that references To create a new document, the client constructs a URI that references
the location where the document is to be placed. This URI MUST NOT the location where the document is to be placed. This URI MUST NOT
contain a NodeSelector component, and MUST meet the constraints contain a NodeSelector component. The client then invokes a PUT
described in Section 5.1. The client then invokes a PUT method on method on that URI.
that URI.
The content in the request MUST be an XML document compliant to the The content in the request MUST be an XML document compliant to the
schema associated with the application usage defined by the URI. For schema associated with the application usage defined by the URI. For
example, if the client performs a PUT operation to http:// example, if the client performs a PUT operation to http://
xcap.example.com/services/presence-lists/users/joe/mybuddies, xcap.example.com/services/presence-lists/users/joe/mybuddies,
presence-lists is the application unique ID, and the schema defined presence-lists is the application unique ID, and the schema defined
by it would dictate the body of the request. by it would dictate the body of the request.
6.2 Replace an Existing Document 6.2 Replace an Existing Document
skipping to change at page 10, line 48 skipping to change at page 12, line 45
To delete a document, the client constructs a URI that references the To delete a document, the client constructs a URI that references the
document to be deleted. By definition this URI will not contain a document to be deleted. By definition this URI will not contain a
NodeSelector component. The client then invokes a DELETE operation on NodeSelector component. The client then invokes a DELETE operation on
the URI to delete the document. the URI to delete the document.
6.4 Fetching a Document 6.4 Fetching a Document
As one would expect, fetching a document is trivially accomplished by As one would expect, fetching a document is trivially accomplished by
performing an HTTP GET request with the Request URI set to the performing an HTTP GET request with the Request URI set to the
document to be fetched. It is useful for clients to perform document to be fetched. It is useful for clients to perform
conditional GETs using the If-Modified-Since header field, in order conditional GETs using the If-Match header field, in order to check
to check if a locally cached copy of the document is still valid. if a locally cached copy of the document is still valid. An HTTP
server MUST return Etags for entities that represent resources
managed by XCAP.
6.5 Creating a New Element 6.5 Creating a New Element
To create a new XML element within an existing document, the client
constructs a URI whose Document-URI points to the document to be
modified. The Node-Selector MUST be present, containing an expression
identifying the point in the document where the new element is to be
added. The node-set selected by the expression MUST contain only a
single XML element.
The client then invokes the HTTP POST method. The content in the
request MUST be an XML document. That XML document MUST be conformant
to the schema associated with the application usage defined by the
URI. The server will insert the document such that the first element
of the document becomes the next sibling immediately following the
element specified by the Request-URI. The client SHOULD be certain,
before making the request, that the resulting modified document will
also be conformant to the schema.
6.6 Replacing an Element in the Document
Replacing an element of the document constitutes storage of a To create a new XML element within an existing document, the client
supplied entity under the specified URI, and is therefore constructs a URI whose document URI points to the document to be
accomplished with the PUT method (as opposed to POST, which will modified. The node selector MUST be present in the URI. The node
insert). The client constructs a URI whose Document-URI points to the selector is constructed such that it meets two constraints. First, if
document to be modified. The Node-Selector MUST be present, evaluated against the current document, the result is a no-match.
containing an expression identifying the element whose value is to be Secondly, if the element was added to the document as desired by the
replaced. The node-set selected by the expression MUST contain only a client, the node selector would select that element.
single XML element.
The client then invokes the PUT method. The entity of the request The client then invokes the HTTP PUT method [[OPEN ISSUE: what is the
MUST be of type text/plain. The server will take the value of the content type?]]. The content in the request MUST be an XML element.
element specified by the request URI, and replace it with the content The server will insert the element into the document such that the
of the PUT request. Here, value refers to the binary contents of an node selector, if evaluated by the server, would return the content
XML document, starting with the beginning tag of the element, and present in the request. The client SHOULD be certain, before making
ending with the end tag. This differs from the "string value" defined the request, that the resulting modified document will also be
in XPath, which refers only to the values of the text element
descendants of an element. The client SHOULD be certain, before
making the request, that the resulting modified document will be
conformant to the schema. conformant to the schema.
The body of the request here is of type text/plain because the value It is important to note that the element might potentially be
of an element need not be a valid XML document; frequently, it will inserted in the document in several different ways, and still meet
be text or CDATA. Of course, the value of an XML element may be other the constraints defined above. This is analagous to the case when a
XML elements, in which case the body of the request will be an XML new file is PUT into a directory on a server; the location of that
document fragment, and by itself not compliant to any schema. file within the directory is not specified, and is up the local file
system to decide. The only guarantee is that GET(PUT(x)) returns
document x.
Note that this operation only modifies the value of an element. It 6.6 Replacing an Element in the Document
cannot modify the attributes of the element. To do that, the replace
attribute operation is performed. Replacing an element of the document is also accomplished with PUT.
The only difference with the behavior above for insertion is that the
node selector, when evaluated against the current document, is a
match for an element in the current document. That element is
removed, and replaced with the content of the PUT request.
6.7 Delete an Element 6.7 Delete an Element
To delete elements from a document, the client constructs a URI whose To delete elements from a document, the client constructs a URI whose
Document-URI points to the document containing the elements to be document URI points to the document containing the elements to be
deleted. The Node-Selector MUST be present, containing an expression deleted. The node selector MUST be present, and identify the specific
identifying the elements to be deleted. Unlike most of the other element to be deleted.
operations, the node-set selected by the expression MAY contain
multiple elements.
The client then invokes the HTTP DELETE method. All of the elements The client then invokes the HTTP DELETE method. The server will
specified by the node set will be deleted by the server. The body of remove the element from the document. The client SHOULD be certain,
the request SHOULD be empty. The client SHOULD be certain, before before making the request, that the resulting modified document will
making the request, that the resulting modified document will also be also be conformant to the schema.
conformant to the schema.
6.8 Fetch an Element 6.8 Fetch an Element
To fetch an element of a document, the client constructs a URI whose To fetch an element of a document, the client constructs a URI whose
Document-URI points to the document containing the element to be document URI points to the document containing the element to be
fetched. The Node-Selector MUST be present, containing an expression fetched. The node selector MUST be present, and must identify the
identifying the element whose value is to be fetched. The node-set element to be fetched.
selected by the expression MUST contain only a single XML element.
The client then invokes the GET method. The response will contain an
XML document with the specified element as the one and only child of
the document root.
OPEN ISSUE: This only allows you to get one element at a time. We The client then invokes the GET method. The response will contain
could allow the XPath expression to specify multiple elements, and that XML element. Specifically, it contains the content of the XML
then the response contains a document with each of those elements document, starting with the opening bracket for the begin tag for
as a child of the document root. However, that document might not that element, and ending with the closing bracket for the end tag for
be compliant to the schema, and worse, the document doesnt that element.
actually reflect any specific sub-tree of the actual document.
6.9 Create an Attribute 6.9 Create an Attribute
To create an attribute in an existing element of a document, the To create an attribute in an existing element of a document, the
client constructs a URI whose Document-URI points to the document to client constructs a URI whose document URI points to the document to
be modified. The Node-Selector MUST be present, containing an be modified. The node selector MUST be present. The node selector is
expression identifying an attribute that is to created. Specifically, constructed such that it meets two constraints. First, if evaluated
the last location step of the expression MUST specify an attribute against the current document, the result is a no-match. Secondly, if
axis, and the context MUST specify a single element that exists the attribute was added to the document as desired by the client, the
within the document. node selector would select that attribute.
The client then invokes the HTTP POST method. The content defined by
the request MUST be of type text/plain. A new attribute is added to
the element defined by the context, with the name specified by the
node test in the last location step, with a value specified by the
body of the request. If an attribute of this name already exists, it
is replaced. The client SHOULD be certain, before making the request,
that the resulting modified document will also be conformant to the
schema.
6.10 Replacing Attributes
To replace an attribute in an existing element of a document, the
client constructs a URI whose Document-URI points to the document to
be modified. The Node-Selector MUST be present, containing an
expression identifying an attribute that is to be replaced.
The client then invokes the HTTP PUT method. The content defined by The client then invokes the HTTP PUT method. The content defined by
the request MUST be of type text/plain. The value of the attribute the request MUST be compliant to the grammar for Attribute as defined
defined by the Node-Selector is replaced by the body of the request. in XML 1.0 [[OPEN ISSUE: content type?]]. The server will add that
attribute such that, if the node selector is evaluated on the
resulting document, it returns the attribute present in the request.
The client SHOULD be certain, before making the request, that the The client SHOULD be certain, before making the request, that the
resulting modified document will also be conformant to the schema. resulting modified document will also be conformant to the schema.
6.10 Replacing Attributes
Replacing an attribute of the document is also accomplished with PUT.
The only difference with the behavior above for insertion is that the
node selector, when evaluated against the current document, is a
match for an attribute in the current document. That attribute is
removed, and replaced with the content of the PUT request.
6.11 Deleting Attributes 6.11 Deleting Attributes
To delete attributes from the document, the client constructs a URI To delete attributes from the document, the client constructs a URI
whose Document-URI points to the document containing the attributes whose document URI points to the document containing the attributes
to be deleted. The Node-Selector MUST be present, containing an to be deleted. The node selector MUST be present, and evaluate to an
expression identifying the attributes to be deleted. Unlike most of attribute in the document to be deleted.
the other operations, the node-set selected by the expression MAY
contain multiple attributes.
The client then invokes the HTTP DELETE method. All of the attributes The client then invokes the HTTP DELETE method. The server will
specified by the node set will be deleted by the server. The body of remove the attribute from the document. The client SHOULD be certain,
the request SHOULD be empty. The client SHOULD be certain, before before making the request, that the resulting modified document will
making the request, that the resulting modified document will also be also be conformant to the schema.
conformant to the schema.
6.12 Fetching Attributes 6.12 Fetching Attributes
To fetch an attribute of a document, the client constructs a URI To fetch an attribute of a document, the client constructs a URI
whose Document-URI points to the document containing the attribute to whose Document-URI points to the document containing the attribute to
be fetched. The Node-Selector MUST be present, containing an be fetched. The node selector MUST be present, containing an
expression identifying the attribute whose value is to be fetched. expression identifying the attribute whose value is to be fetched.
The node-set selected by the expression MUST contain only a single
XML attribute.
The client then invokes the GET method. The response will contain an
text/plain document with the value of the specified attribute.
6.13 Fetching Metadata The client then invokes the GET method. The response will contain
Elements and attributes in an XML document have various meta-data document with the specified attribute, formatted according to the
associated with them. For example, and XML element has a certain grammar of Attribute as defined in the XML 1.0 specifications.
number of child elements. That number is a piece of meta-data that
describes the element. Currently, there is no way to fetch meta-data
for XML elements or attributes.
OPEN ISSUE: Is this restriction OK? XPath does specify functions
for computing meta-data about node sets. We can't use them since
XCAP mandates that the request URI be a location set, which does
not include these other functions. We could relax the constraint
if this is deemed important.
6.14 Read/Modify/Write Transactions 6.13 Read/Modify/Write Transactions
It is anticipated that a common operation will be to read the current It is anticipated that a common operation will be to read the current
version of a document or element, modify it on the client, and then version of a document or element, modify it on the client, and then
write the change back to the server. In order for the results to be write the change back to the server. In order for the results to be
consistent with the client's expectations, the operation must be consistent with the client's expectations, the operation must be
atomic. atomic.
To accomplish this, the client stores the value of the Last-Modified To accomplish this, the client makes use of entity tags returned by
header field from the response to its GET operation used to read the the server in a GET operation used to read the element, attribute, or
element, attribute, or document that is to be modified. To guarantee document that is to be modified. To guarantee atomicity, the PUT
atomicity, the PUT or POST operation used to write the changes back operation used to write the changes back to the server MUST contain
to the server MUST contain an If-Unmodified-Since header field, whose an If-Match header field, whose value is equal to the entity tag from
value is equal to the value from the prior GET response. If the the prior GET response. If the request fails with a 412 response, the
request fails with a 412 response, the client knows that another client knows that another update of the data has occurred before it
update of the data has occurred before it was able to write the was able to write the results back. The client can then fetch the
results back. The client can then fetch the most recent version, and most recent version, and attempt its modification again.
attempt its modification again.
7. Server Behavior Because there are no batching operations defined in HTTP, that would
allow for a number of separate create, modify or delete operations to
be performed atomically, designers of application usages should take
care to structure their schemas so that operations that need to be
performed atomically can be done in a single operation.
TODO: Specify an XML body type for the responses that contains 7. Server Behavior
error conditions or success results.
An XCAP server is an HTTP 1.1 compliant origin server. The behaviors An XCAP server is an HTTP 1.1 compliant origin server. The behaviors
mandated by this specification relate to the way in which the HTTP mandated by this specification relate to the way in which the HTTP
URI is interpreted and the content is constructed. URI is interpreted and the content is constructed.
An XCAP server MUST be explicitly aware of the application usage An XCAP server MUST be explicitly aware of the application usage
against which requests are being made. That is, the server must be against which requests are being made. That is, the server must be
explicitly configured to handle URIs for each specific application explicitly configured to handle URIs for each specific application
usage, and must be aware of the constraints imposed by that usage, and must be aware of the constraints imposed by that
application usage. application usage. Furthermore, an XCAP server MUST be aware of all
of the XML namespaces present in any documents it manages. This is to
OPEN ISSUE: It may be possible to remove this restriction by ensure that any data constraints or data interdependencies imposed by
allowing an application usage to define operation in a server that a future application usage are properly supported by the server. It
doesnt understand the usage. That may require some capabilities is also required to ensure that authorization policies are properly
discovery to be introduced, this constraint didnt seem that implemented.
problematic.
When the server receives a request, the treatment depends on the URI. When the server receives a request, the treatment depends on the URI.
If the URI refers to an application usage not understood by the If the URI refers to an application usage not understood by the
server, the server MUST reject the request with a 404 (Not Found) server, the server MUST reject the request with a 404 (Not Found)
response. If the URI refers to a user that is not recognized by the response. If the URI refers to a user that is not recognized by the
server, it MUST reject the request with a 404 (Not Found). server, it MUST reject the request with a 404 (Not Found).
Next, the server authenticates the request. All XCAP servers MUST Next, the server authenticates the request. All XCAP servers MUST
support HTTP Digest [6]. Furthermore, servers MUST support HTTP over support HTTP Digest [6]. Furthermore, servers MUST support HTTP over
TLS, RFC 2818 [7]. It is RECOMMENDED that administrators use an HTTPS TLS, RFC 2818 [9]. It is RECOMMENDED that administrators use an HTTPS
URI as the XCAP root services URI, so that the digest client URI as the XCAP root services URI, so that the digest client
authentication occurs over TLS. authentication occurs over TLS.
Next, the server determines if the client has authorization to Next, the server determines if the client has authorization to
perform the requested operation on the resource. The default perform the requested operation on the resource. The default
authorization policy is that only client X can access (create, read, authorization policy is that only client X can access (create, read,
write, modify or delete) resources under the "users/X" directory. An write, modify or delete) resources under the "users/X" directory. An
application usage can specify an alternate default authorization application usage can specify an alternate default authorization
policy specific to that usage. Of course, an administrator or policy specific to that usage. The server may also know of an
privileged user can override the default authorization policy, application usage that itself defines authorization policies for
although this specification provides no means for doing that. another application usage. Of course, an administrator or privileged
Generally, if users need to be able to control authorization for user can override the default authorization policy, although this
access to XCAP data, an XCAP application usage should be specified specification provides no means for doing that.
which allows the user to set the policies as needed.
OPEN ISSUE: This is different from ACAP, where authorization
policies are built into the protocol. I think the default
generally will suffice, so I would rather not burden the baseline
protocol with it.
Once authorized, the specific behavior depends on the method and what Once authorized, the specific behavior depends on the method and what
the URI refers to. the URI refers to.
7.1 POST Handling 7.1 POST Handling
If the URI contains only a Document-URI, the server examines the Resources managed by XCAP do not represent processing scripts. As a
entity body of the request. If there is no entity in the body, the result, POST operations to XCAP URIs is not defined. A server
server MUST reject the request with a 409 response. If there is an receiving such a request SHOULD return a 405.
entity, but it is not well-formed, the server MUST reject the request
with a 409 response. If it is well-formed, but not compliant to the
schema associated with the application usage, the server MUST reject
the request with a 409 response. If it is compliant to the schema,
the server MUST store the document at the requested URI. If there is
not already a document stored at that URI, a 201 (Created) response
code MUST be sent, and it MUST include a Location header field
containing the value of the URI for the document (which will be the
same as the one in the Request-URI). Otherwise, a 200 OK response is
returned, and the document in the body replaces the existing one at
that URI. For either a 200 or 201 response, the new document is
returned in the body of the response, with a Content-Type equal to
the MIME type defined by the application usage.
If the Request URI contains a Node-Selector, the server MUST verify
that the document defined by the Document-URI exists. If no such
document exists on the server, the server MUST reject the request
with a 409 response code. If the document does exist, the server
evaluates the Node-Selector as an XPath RelativeLocationPath,
relative to the root of the document. If the Node-Selector does not
comply to the grammar for RelativeLocationPath, the server MUST
reject the request with a 400 response code. If the Node-Selector
does comply, and it evaluates to anything other than the empty set, a
single attribute node or single element node, the server MUST reject
the request with a 409 response code.
If the Node-Selector evaluates to the empty set, and the last
location step is on the attribute axis, and the expression without
the last location step evaluates to a single element node, the server
adds an attribute to that element. Its name is the name given in the
node test of the last location step, and its value is taken from the
body of the request. The server then generates a 200 OK response,
whose body contains the value of the attribute, with a Content-Type
of text/plain.
If the Node-Selector evaluates to a single element node, the server
takes the content of the request, and inserts it into the document
specified by the URI such that the selected element is the immediate
sibling of the nodes defined by the content of the request. The
server then generates a 200 OK response, whose body contains the
parent element of the new elements just inserted. The parent element
is represented by extracting the contents of the XML document,
starting with, and including, the begin tag of the element, up to,
and including, the end tag for the element. The Content-Type of the
response is set to application/xml.
OPEN ISSUE: We can't use the MIME type for the application usage,
since the schema may not allow for the document to start with any
element defined by the schema. Is that OK? I think so.
If the Node-Selector evaluates to a single attribute node, the server
takes the content of the request, and sets it as the value of the
attribute specified by the body of the request. The server then
generates a 200 OK response, whose body contains the value of the
attribute, with a Content-Type of text/plain.
If the result of the POST is a document which does not comply with
the XML schema for the application usage, the server MUST NOT perform
the POST, and MUST reject the request with a 409 (Conflict).
7.2 PUT Handling 7.2 PUT Handling
When the Request URI contains only the Document-URI, the semantics of The behavior of a server in receipt of a PUT request is as specified
PUT are as defined in HTTP 1.1 Section 9.6 - the content of the in HTTP 1.1 Section 9.6 - the content of the request is placed at the
request is placed at the specified location. specified location. This section serves to define the notion of
"placement" and "specified location" within the context of XCAP
If the Request URI contains a Node-Selector, the server MUST verify resources.
that the document defined by the Document-URI exists. If no such
document exists on the server, the server MUST reject the request
with a 409 response code. If the document does exist, the server
evaluates the Node-Selector as an XPath RelativeLocationPath,
relative to the root of the document. If the Node-Selector does not
comply to the grammar for RelativeLocationPath, the server MUST
reject the request with a 400 response code. If the Node-Selector
does comply, and it evaluates to anything other than the a single
element node or attribute node, the server MUST reject the request
with a 409 response code.
If the Node-Selector evaluates to a single element node, the server If the request URI represents a document (i.e., there is no node
takes the content of the request, and replaces the value of that selector component), the content of the request MUST be a valid XML
element (where value is defined as all of the content - elements, document, and MUST be compliant to the schema associated with the
text, or CDATA - between the begin and end tags of the element) with application usage in the URI. If it is not, the request MUST be
that content. The server then returns a 200 OK response. rejected with a 409 response. If the request URI matches a document
that exists on the server, that document is replaced by the content
of the request. If the request URI does not match a document that
exists on the server, the server adds the document to its repository,
and associates it with the URI in the request URI. Note that this may
require the creation of one or more "directories" on the server.
OPEN ISSUE: PUT is not quite right here, since a subsequent GET on If the Request URI represents an XML element (i.e., it contains a
the same URI will not return exactly the same thing - the begin node selector, but no attribute selector) the server MUST verify that
and end tags will be present. This may need to be POST, but then, the document defined by the document URI exists. If no such document
how to differentiate a replace with an append operation? exists on the server, the server MUST reject the request with a 409
response code. The content of the request MUST be a single XML
element and associated content (including children elements). If the
request URI matches an element within the document, that element is
removed, and replaced with the content of the request. If the request
URI does not match an element in the document, the server inserts the
content of the request as a new element in the document, such that
the resulting document is compliant to the schema, and such that the
request URI, when evaluated, would now point to the element which was
inserted. There may be more than one way to perform such an
insertion; in that case, it is the discretion of the implementor as
to how it is done. It may also be possible that the insertion cannot
be done without other additional elements being inserted, or cannot
be done because the new element is not compliant to the schema. In
such a case, the server MUST return a 409 response code. In all
cases, the resulting document MUST be compliant to the schema.
If the Node-Selector evaluates to a single attribute node, the server If the Request URI represents an XML attribute (i.e., it contains a
takes the content of the request, and sets it as the value of the node selector and an attribute selector) the server MUST verify that
attribute. It then returns a 200 OK response. the document defined by the document URI exists. If no such document
exists on the server, the server MUST reject the request with a 409
response code. The content of the request MUST be a single XML
attribute, compliant to the grammar for Attribute as defined in XML
1.0 (i.e., name=value). If the request URI matches an ent within the
document, that attribute is removed, and replaced with the content of
the request. If the request URI does not match an attribute in the
document, the server inserts the content of the request as a new
attribute in the document, such that the resulting document is
compliant to the schema, and such that the request URI, when
evaluated, would now point to the attribute which was inserted. There
may be more than one way to perform such an insertion; in that case,
it is the discretion of the implementor as to how it is done. It may
also be possible that the insertion cannot be done without other
additional content being inserted, or cannot be done because the new
attribute is not compliant to the schema. In such a case, the server
MUST return a 409 response code. In all cases, the resulting document
MUST be compliant to the schema.
If the result of the PUT is a document which does not comply with the If the creation or insertion was successful, the server returns a 200
XML schema for the application usage, the server MUST NOT perform the OK or 201 Created, as appropriate.
PUT, and MUST reject the request with a 409 (Conflict).
7.3 GET Handling 7.3 GET Handling
If the request URI contains only a Document-URI, the server returns The semantics of GET are as specified in RFC 2616. This section
the document specified by the URI if it exists, else returns a 404 clarifies the specific content to be returned for a particular URI
response. that represents an XCAP resource.
If the request URI specifies a Node-Selector, the server verifies
that the document specified by the Document-URI exists. If it does
not exist, the server returns a 404 (Not Found) response. If the
document does exist, the server evaluates the Node-Selector as an
XPath RelativeLocationPath, relative to the root of the document. If
the Node-Selector does not comply to the grammar for
RelativeLocationPath, the server MUST reject the request with a 400
response code. If the Node-Selector does comply, and it evaluates to
anything other than the a single element node or attribute node, the
server MUST reject the request with a 409 response code.
If the Node-Selector evaluates to a single element node, the server
takes the document text, starting with, and including, the begin tag
of the element, up to, and including, the end tag for the element,
and places it into the body of a 200 OK response, setting the
Content-Type to application/xml.
If the Node-Selector evaluates to a single attribute node, the server
takes the value of the attribute and returns it as the content of the
200 OK response, setting the Content-Type to text/plain.
OPEN ISSUE: Do we need to say anything about HEAD? We havent said If the request URI contains only a document URI, the server returns
anything about meta-data so far; most of that is just regular HTTP the document specified by the URI if it exists, else returns a 404
usage, I think. response. If the request URI contains a node selector, and that node
selector identifies an XML element in an existing document, that
element is returned in the 200 response. The content of the response
is the portion of the XML document starting with the left bracket of
the begin tag of the element, ending with the right bracket of the
end tag of the element. If the request URI contains a node selector,
and that node selector contains an attribute selector, and that
attribute exists in the specified document, the server returns that
attribute, formatted as Attribute in the XML 1.0 specifications. In
all cases, if the referenced resource does not exist, a 404 is
returned.
7.4 DELETE Handling 7.4 DELETE Handling
The semantics of DELETE are as specified in RFC 2616. This section
clarifies the specific content to be deleted for a particular URI
that represents an XCAP resource.
If the request URI contains only a Document-URI, the server deletes If the request URI contains only a Document-URI, the server deletes
the document specified by the URI if it exists and returns a 200 OK the document specified by the URI if it exists and returns a 200 OK
response, else returns a 404 response. response, else returns a 404 response. If the request URI specifies a
Node-Selector, the server verifies that the document specified by the
If the request URI specifies a Node-Selector, the server verifies Document-URI exists. If it does not exist, the server returns a 404
that the document specified by the Document-URI exists. If it does (Not Found) response. If the document does exist, and the node
not exist, the server returns a 404 (Not Found) response. If the selector specifies an XML element that exists, that element is
document does exist, the server evaluates the Node-Selector as an removed from the document. If the document does exist, and the node
XPath RelativeLocationPath, relative to the root of the document. If selector specifies an XML attribute that exists in the document, that
the Node-Selector does not comply to the grammar for attribute is removed from the document. If the node selector returns
RelativeLocationPath, the server MUST reject the request with a 400 a no-match, a 404 (Not Found) is returned. However, if removal of the
response code. If the Node-Selector does comply, and it evaluates to element or attribute would result in a document which does not comply
the empty set, the server MUST reject the request with a 404 (Not
Found).
Otherwise, the server removes all of the data defined by the
node-set. Specifically, any elements in the node set are removed from
the document, and any attributes in the node set are removed from the
document. It then returns a 200 OK response.
If the result of the deletion is a document which does not comply
with the XML schema for the application usage, the server MUST NOT with the XML schema for the application usage, the server MUST NOT
perform the deletion, and MUST reject the request with a 409 perform the deletion, and MUST reject the request with a 409
(Conflict). (Conflict).
7.5 Managing Modification Times 7.5 Managing Etags
An XCAP server MUST maintain modification times for all resources
that can be referenced by a URI. Specifically, this means that each
document, and within the document, each element and attribute, MUST
be associated with a modification time maintained by the server.
These modification times are needed to support condition GET, POST
and PUT requests.
When a PUT or POST request is made that creates or replaces a An XCAP server MUST maintain entity tags for all resources that can
document, the modification time of that document and all elements and be referenced by a URI. Specifically, this means that each document,
attributes within is set to the current time. When a PUT request is and within the document, each element and attribute, MUST be
made to a URI referencing an XML element, the modification time of associated with an entity tag maintained by the server. These entity
that element and all of its enclosed children and their attributes is tags are needed to support conditional PUT and DELETE requests.
set to the current time. Furthermore, the modification time of all
elements which are ancestors of that element have their modification
time set to the current time. However, the modification times of
attributes belong to elements that are ancestors of the modified
element do not have their modification times changed.
When a POST request is made to a URI referencing an XML element, the When a PUT request is made that creates or replaces a document, the
modification time of all of the elements and their attributes within entity tag of that document and all elements and attributes within is
the document in the body of the request is set to the current time. updated.
Furthermore, the modification time of the element which is the new
parent of the elements in the request, and all of its ancestors, have
their modification time set to the current time. However, the
modification times of their attributes are unchanged.
When a POST request is made to a URI referencing an XML attribute, When a PUT request is made to a URI referencing an XML element, the
the modification time of that attribute, its element, and all entity tag of that element, its attributes, and all of its enclosed
elements that are ancestors of that element is set to the current children and their attributes is updated. For a PUT or DELETE request
time. for an XML element, the entity tag of all elements which are
ancestors of that element are updated. However, the entity tags of
attributes belonging to elements that are ancestors of the modified
element do not have their entity tags changed, because those
resources have not actually changed.
When a DELETE request is made to a URI referencing an element, the When a PUT request is made to a URI referencing an XML attribute, the
modification time of all ancestors of that element is set to the entity of that attribute is updated. For a PUT or DELETE request for
current time. When a DELETE request is made to a URI referencing an an attribute, the entity tags for its element, and all elements that
attribute, the modification time of its element, and all ancestors of are ancestors of that element are updated.
that element, is set to the current time.
8. Examples 8. Examples
This section goes through several examples, making use of the This section goes through several examples, making use of the
presence-lists [17] XCAP application usage. resource-lists [17] XCAP application usage.
First, a user Bill creates a new presence-list, initially with no First, a user Bill creates a new resource-list, initially with no
users in it: users in it:
PUT PUT
http://xcap.example.com/services/presence-lists/users/bill/fr.xml HTTP/1.1 http://xcap.example.com/services/presence-lists/users/bill/fr.xml HTTP/1.1
Content-Type:application/presence-lists+xml Content-Type:application/presence-lists+xml
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<presence-lists xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <resource-lists xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<list name="friends" uri="sip:friends@example.com" subscribable="true"> <list name="friends" uri="sip:friends@example.com" subscribeable="true">
</list> </list>
</presence-lists> </resource-lists>
Next, Bill adds an entry to the list: Next, Bill adds an entry to the list:
PUT PUT
http://xcap.example.com/services/presence-lists/users/bill/fr.xml? http://xcap.example.com/services/presence-lists/users/bill/fr.xml?
presence-lists/list[@name="friends"] HTTP/1.1 resource-lists/list[@name="friends"]/entry HTTP/1.1
Content-Type:text/plain Content-Type:text/plain
<entry name="Bill" uri="sip:bill@example.com"> <entry name="Bob" uri="sip:bob@example.com">
<display-name>Bill Doe</display-name> <display-name>Bob Jones</display-name>
</entry> </entry>
Note how the URI in the PUT request selects the list element whose Next, Bill fetches the list:
name attribute is "friends". The body of that request replaces the
existing value of that element, which was empty. GET
http://xcap.example.com/services/presence-lists/users/bill/fr.xml HTTP/1.1
And the result is:
HTTP/1.1 200 OK
Etag: "wwhha"
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<resource-lists xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<list name="friends" uri="sip:friends@example.com"
subscribeable="true">
<entry name="Bob" uri="sip:bob@example.com">
<display-name>Bob Jones</display-name>
</entry>
</list>
</resource-lists>
Next, Bill adds another entry to the list, which is another list that Next, Bill adds another entry to the list, which is another list that
has three entries: has three entries:
POST PUT
http://xcap.example.com/services/presence-lists/users/bill/fr.xml? http://xcap.example.com/services/presence-lists/users/bill/fr.xml?
presence-lists/list[@name="friends"]/entry[@name="Bill"] HTTP/1.1 presence-lists/list[@name="friends"]/list[@name="close-friends"] HTTP/1.1
Content-Type:text/plain Content-Type:text/plain
<list name="close-friends" uri="sip:close-friends@example.com" <list name="close-friends" uri="sip:close-friends@example.com"
subscribable="true"> subscribeable="true">
<entry name="Joe" uri="sip:joe@example.com"> <entry name="Joe" uri="sip:joe@example.com">
<display-name>Joe Smith</display-name> <display-name>Joe Smith</display-name>
</entry> </entry>
<entry name="Nancy" uri="sip:nancy@example.com"> <entry name="Nancy" uri="sip:nancy@example.com">
<display-name>Nancy Gross</display-name> <display-name>Nancy Gross</display-name>
</entry> </entry>
<entry name="Petri" uri="sip:petri@example.com"> <entry name="Petri" uri="sip:petri@example.com">
<display-name>Petri Aukia</display-name> <display-name>Petri Aukia</display-name>
</entry> </entry>
</list> </list>
skipping to change at page 22, line 39 skipping to change at page 22, line 12
Bill decides to check on the URI for Nancy: Bill decides to check on the URI for Nancy:
GET GET
http://xcap.example.com/services/presence-lists/users/bill/fr.xml? http://xcap.example.com/services/presence-lists/users/bill/fr.xml?
presence-lists/list/list/entry[@name="Nancy"]/@uri HTTP/1.1 presence-lists/list/list/entry[@name="Nancy"]/@uri HTTP/1.1
and the server responds: and the server responds:
HTTP/1.1 200 OK HTTP/1.1 200 OK
Etag: "ad88"
Content-Type:text/plain Content-Type:text/plain
sip:nancy@example.com uri="sip:nancy@example.com"
9. Security Considerations 9. Security Considerations
Frequently, the data manipulated by XCAP contains sensitive Frequently, the data manipulated by XCAP contains sensitive
information. To avoid eavesdroppers from seeing this information, information. To avoid eavesdroppers from seeing this information, it
XCAP RECOMMENDS that an admistrator hand out an https URI as the XCAP is RECOMMENDED that an admistrator hand out an https URI as the XCAP
root services URI. This will result in TLS-encrypted communications root services URI. This will result in TLS-encrypted communications
between the client and server, preventing any eavesdropping. between the client and server, preventing any eavesdropping.
Client and server authentication are also important. A client needs Client and server authentication are also important. A client needs
to be sure it is talking to the server it believes it is contacting. to be sure it is talking to the server it believes it is contacting.
Otherwise, it may be given false information, which can lead to Otherwise, it may be given false information, which can lead to
denial of service attacks against a client. To prevent this, a client denial of service attacks against a client. To prevent this, a client
SHOULD attempt to upgrade [8] any connections to TLS. Similarly, SHOULD attempt to upgrade [10] any connections to TLS. Similarly,
authorization of read and write operations against the data is authorization of read and write operations against the data is
important, and this requires client authentication. As a result, a important, and this requires client authentication. As a result, a
server SHOULD challenge a client using HTTP Digest [6] to establish server SHOULD challenge a client using HTTP Digest [6] to establish
its identity, and this SHOULD be done over a TLS connection. its identity, and this SHOULD be done over a TLS connection.
10. IANA Considerations 10. IANA Considerations
This specification instructs IANA to create a new registry for XCAP This specification instructs IANA to create a new registry for XCAP
application usage IDs (AUIDs). application usage IDs (AUIDs).
XCAP AUIDs are registered by the IANA when they are published in XCAP AUIDs are registered by the IANA when they are published in
standards track RFCs. The IANA Considerations section of the RFC standards track RFCs. The IANA Considerations section of the RFC
must include the following information, which appears in the IANA must include the following information, which appears in the IANA
registry along with the RFC number of the publication. registry along with the RFC number of the publication.
Name of the AUID. The name MAY be of any length, but SHOULD be no Name of the AUID. The name MAY be of any length, but SHOULD be no
more than twenty characters long. The name MUST consist of more than twenty characters long. The name MUST consist of
alphanum [9] characters only. alphanum [11] characters only.
Descriptive text that describes the application usage. Descriptive text that describes the application usage.
Normative References Normative References
[1] Thompson, H., Beech, D., Maloney, M. and N. Mendelsohn, "XML [1] Thompson, H., Beech, D., Maloney, M. and N. Mendelsohn, "XML
Schema Part 1: Structures", W3C REC REC-xmlschema-1-20010502, Schema Part 1: Structures", W3C REC REC-xmlschema-1-20010502,
May 2001. May 2001.
[2] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L., [2] Fielding, R., Gettys, J., Mogul, J., Nielsen, H., Masinter, L.,
Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol --
HTTP/1.1", RFC 2616, June 1999. HTTP/1.1", RFC 2616, June 1999.
[3] Bradner, S., "Key words for use in RFCs to Indicate Requirement [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997. Levels", BCP 14, RFC 2119, March 1997.
[4] Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC [4] Murata, M., St. Laurent, S. and D. Kohn, "XML Media Types", RFC
3023, January 2001. 3023, January 2001.
[5] Clark, J. and S. DeRose, "XML Path Language (XPath) Version [5] Clark, J. and S. DeRose, "XML Path Language (XPath) Version
1.0", W3C REC REC-xpath-19991116, November 1999. 1.0", W3C REC REC-xpath-19991116, November 1999.
[6] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., [6] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
Leach, P., Luotonen, A. and L. Stewart, "HTTP Authentication: Leach, P., Luotonen, A. and L. Stewart, "HTTP Authentication:
Basic and Digest Access Authentication", RFC 2617, June 1999. Basic and Digest Access Authentication", RFC 2617, June 1999.
[7] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. [7] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997.
[8] Khare, R. and S. Lawrence, "Upgrading to TLS Within HTTP/1.1", [8] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform
RFC 2817, May 2000. Resource Identifiers (URI): Generic Syntax", RFC 2396, August
1998.
[9] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., [9] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
Peterson, J., Sparks, R., Handley, M. and E. Schooler, "SIP:
Session Initiation Protocol", RFC 3261, June 2002. [10] Khare, R. and S. Lawrence, "Upgrading to TLS Within HTTP/1.1",
RFC 2817, May 2000.
[11] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A.,
Peterson, J., Sparks, R., Handley, M. and E. Schooler, "SIP:
Session Initiation Protocol", RFC 3261, June 2002.
Informative References Informative References
[10] Rosenberg, J., "A Presence Event Package for the Session [12] Rosenberg, J., "A Presence Event Package for the Session
Initiation Protocol (SIP)", draft-ietf-simple-presence-10 (work Initiation Protocol (SIP)", draft-ietf-simple-presence-10 (work
in progress), January 2003. in progress), January 2003.
[11] Rosenberg, J., "A Watcher Information Event Template-Package [13] Rosenberg, J., "A Watcher Information Event Template-Package
for the Session Initiation Protocol (SIP)", for the Session Initiation Protocol (SIP)",
draft-ietf-simple-winfo-package-05 (work in progress), January draft-ietf-simple-winfo-package-05 (work in progress), January
2003. 2003.
[12] Rosenberg, J., "An Extensible Markup Language (XML) Based [14] Rosenberg, J., "An Extensible Markup Language (XML) Based
Format for Watcher Information", Format for Watcher Information",
draft-ietf-simple-winfo-format-04 (work in progress), January draft-ietf-simple-winfo-format-04 (work in progress), January
2003. 2003.
[13] Rosenberg, J., Roach, A. and B. Campbell, "A Session Initiation [15] Roach, A., Rosenberg, J. and B. Campbell, "A Session Initiation
Protocol (SIP) Event Notification Extension for Resource Protocol (SIP) Event Notification Extension for Resource
Lists", draft-ietf-simple-event-list-04 (work in progress), Lists", draft-ietf-simple-event-list-04 (work in progress),
June 2003. June 2003.
[14] Rosenberg, J. and M. Isomaki, "Requirements for Manipulation of [16] Rosenberg, J. and M. Isomaki, "Requirements for Manipulation of
Data Elements in Session Initiation Protocol (SIP) for Instant Data Elements in Session Initiation Protocol (SIP) for Instant
Messaging and Presence Leveraging Extensions (SIMPLE) Systems", Messaging and Presence Leveraging Extensions (SIMPLE) Systems",
draft-ietf-simple-data-req-02 (work in progress), April 2003. draft-ietf-simple-data-req-03 (work in progress), June 2003.
[15] Newman, C. and J. Myers, "ACAP -- Application Configuration [17] Rosenberg, J., "An Extensible Markup Language (XML)
Configuration Access Protocol (XCAP) Usage for Presence
Lists", draft-ietf-simple-xcap-list-usage-00 (work in
progress), June 2003.
[18] Newman, C. and J. Myers, "ACAP -- Application Configuration
Access Protocol", RFC 2244, November 1997. Access Protocol", RFC 2244, November 1997.
[16] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA [19] Narten, T. and H. Alvestrand, "Guidelines for Writing an IANA
Considerations Section in RFCs", BCP 26, RFC 2434, October Considerations Section in RFCs", BCP 26, RFC 2434, October
1998. 1998.
[17] Rosenberg, J., "An Extensible Markup Language (XML) [20] Roach, A., "Session Initiation Protocol (SIP)-Specific Event
Configuration Access Protocol (XCAP) Usage for Presence Lists", Notification", RFC 3265, June 2002.
draft-rosenberg-simple-xcap-list-usage-00 (work in progress),
May 2003.
Author's Address Author's Address
Jonathan Rosenberg Jonathan Rosenberg
dynamicsoft dynamicsoft
600 Lanidex Plaza 600 Lanidex Plaza
Parsippany, NJ 07054 Parsippany, NJ 07054
US US
Phone: +1 973 952-5000 Phone: +1 973 952-5000
 End of changes. 102 change blocks. 
548 lines changed or deleted 518 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/