XCAP Tutorial: XCAP Tutorial Jonathan Rosenberg


Ground Rules: Ground Rules This is a session for level setting People are at different points We will start from the beginning NO QUESTION IS TOO STUPID Disrespect will not be tolerated Please interrupt and ask PLEASE!


Agenda: Agenda Understanding XML Basic XML Concepts Namespaces Schema XPath in Brief HTTP Concepts of Note Etags XCAP Problem Definition XCAP Basics


XML Basics: XML Basics XML is a mechanism for representing structured data Data is represented by a tree Each node in the tree is an element Elements have attributes Attributes qualify the data 'Leaf' Elements can contain text content andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;emailandgt;jdrosen@dynamicsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt;


XML Basics: XML Basics XML Comments Elements can be empty andlt;el-name/andgt; shorthand XML Declaration Version Encoding IETF uses UTF-8 andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;emailandgt;jdrosen@dynamicsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt;


XML Terms: XML Terms Well-formed Meets basic constraints for all XML documents Each open tag has a matching close Unique attribute names Valid Meets the constraints defined by a schema or DTD


XML Namespaces: XML Namespaces Problem Want to combine content from different systems into one document What if both sources define the same name? Example Add information to address book on whether data is synced with PC andlt;stateandgt;synchronizedandlt;/stateandgt; Which state is it? andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;emailandgt;jdrosen@dynamicsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt;


XML Namespaces: XML Namespaces Solution: XML Namespace Elements and attributes are bound to a namespace when defined Namespace is identified with a unique URI A prefix is bound to that URI through a declaration in the document Each element is named with its qualified name The prefix, followed by a colon, followed by the local-name andlt;?xml version='1.0' encoding='UTF-8'? xmlns:post='http://www.post.com' xmlns:sync='http://www.sync.com'andgt; andlt;post:address-bookandgt; andlt;!—This guy is a bozo -- andlt;post:entryandgt; andlt;post:nameandgt;Jonathan Rosenbergandlt;/post:nameandgt; andlt;post:emailandgt;jdrosen@dynamicsoft.comandlt;/post:emailandgt; andlt;post:postalandgt; andlt;post:street paved='true'andgt;600 Lanidex Plandlt;/post:streetandgt; andlt;post:cityandgt;Parsippanyandlt;/post:cityandgt; andlt;post:stateandgt;NJandlt;/post:stateandgt; andlt;post:countryandgt;USAandlt;/post:countryandgt; andlt;/post:postalandgt; andlt;post:ietf-participant/andgt; andlt;sync:stateandgt;synchronizedandlt;/sync:stateandgt; andlt;/entryandgt; andlt;/address-bookandgt;


Importance of Namespaces: Importance of Namespaces Namespaces are like option tags in SIP Group a bunch of things together and give it a name Are useful for talking about extensibility Are useful for negotiating extensibility Provide a generic grouping facility


XML Schema: XML Schema Need a way to define the constraints on an XML document Analagous to a database schema Similar to a grammar W3C has specified two ways DTD Original method Not an XML document Limited expressiveness Schema Newer XML-based Much more expressive Much more complex Works well with namespaces Trend is towards schema


Schema Example: Schema Example andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;xs:schema targetNamespace='http://www.post.com' xmlns:xs='http://www.w3.org/2001/XMLSchema' xmlns='http://www.post.com' elementFormDefault='qualified' attributeFormDefault='unqualified'andgt; andlt;xs:element name='address-book'andgt; andlt;xs:complexTypeandgt; andlt;xs:sequenceandgt; andlt;xs:element name='entry' minOccurs='0' maxOccurs='unbounded'andgt; andlt;xs:complexTypeandgt; andlt;xs:sequenceandgt; andlt;xs:element name='name' type='xs:string'/andgt; andlt;xs:element name='email' type='xs:string'/andgt; andlt;xs:element name='postal'andgt; andlt;xs:complexTypeandgt; andlt;xs:sequenceandgt; andlt;xs:element name='street' type='xs:string'/andgt; andlt;xs:element name='city' type='xs:string'/andgt; andlt;xs:element name='state'andgt; andlt;xs:simpleTypeandgt; andlt;xs:restriction base='xs:string'andgt; andlt;xs:enumeration value='NJ'/andgt; andlt;xs:enumeration value='NY'/andgt; andlt;/xs:restrictionandgt; andlt;/xs:simpleTypeandgt; andlt;/xs:elementandgt; andlt;xs:element name='country' type='xs:string'/andgt; andlt;/xs:sequenceandgt; andlt;/xs:complexTypeandgt; andlt;/xs:elementandgt; andlt;xs:element name='ietf-participant'/andgt; andlt;/xs:sequenceandgt; andlt;/xs:complexTypeandgt; andlt;/xs:elementandgt; andlt;/xs:sequenceandgt; andlt;/xs:complexTypeandgt; andlt;/xs:elementandgt; andlt;/xs:schemaandgt;


XPath: XPath XCAP selection is based on XPath Happens to be a subset Not a normative usage XPath problem statement How to point to specific pieces of an XML document Example: 'The third element named entry' Example: 'All of the elements in a document that have the attribute paved equal to true.' XPath = XML Addressing


Basic Example: Basic Example Want to point to the email element XPath expression address-book/entry/email Just like a unix filesystem path Each 'directory' identifies an element name andlt;?xml version='1.0' encoding='UTF-8'? xmlns:post='http://www.post.com' xmlns:sync=http://www.sync.com xmlns='http://www.post.com'andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Randlt;nameandgt; andlt;emailandgt;jr@dsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lx Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;sync:stateandgt;synchronizedandlt;/sync:stateandgt; andlt;/entryandgt; andlt;/address-bookandgt;


Positional Selectors: Positional Selectors What if there are multiple elements with that name? Can supply predicates which select one of the matching ones Predicates appear in square brackets One such predicate is position Indicates which one by its place in the ordered sequence of matching elements Select second bar: foo/bar[2] Select first bar: foo/bar[1] andlt;fooandgt; andlt;barandgt;Helloandlt;/barandgt; andlt;barandgt;Thereandlt;/barandgt; andlt;/fooandgt;


Select by Attribute Name: Select by Attribute Name You can select elements that have attributes with specific values element[@name='value'] foo/bar[@attr='1'] foo/bar[@attr='2'] foo/bar[@stuff='LOTR'] andlt;fooandgt; andlt;bar attr='1'andgt;Hiandlt;/barandgt; andlt;bar attr='2'andgt;Howandlt;/barandgt; andlt;bar stuff='LOTR'andgt;Areandlt;/barandgt; andlt;/fooandgt;


Selecting Elements: Selecting Elements The result of selecting an element includes The element Its children Its attributes Everything between open bracket of open element to close bracket of close element XPath allows selecting multiple elements XCAP does not use this feature


Selecting Attributes: Selecting Attributes An attribute is selected by prefixing its name with an '@' foo/bar[1]/@attr foo/bar[@attr='2']/@bool foo/movie/@stuff The selected object is JUST the value Different from elements Name would be redundant andlt;fooandgt; andlt;bar attr='1'andgt;Hiandlt;/barandgt; andlt;bar attr='2' bool='y'andgt;Howandlt;/barandgt; andlt;movie stuff='LOTR'andgt;Areandlt;/barandgt; andlt;/fooandgt;


XCAP Problem Space: XCAP Problem Space Motivating use cases Buddy Lists Authorization Policies Hard state presence data


Buddy List Use Case: Buddy List Use Case Client wants to subscribe to a list of users Send SUBSCRIBE to server using SIP event list extension Server retrieves list associated with buddylist URI Generates SUBSCRIBEs to them Client can manage that list Add, remove, modify entries Subscribe Joe Subscribe Bob Subscribe Mary Subscribe List Read List Write List Data Manipulation Server Client Standard Ifaces


Authorization Use Case: Authorization Use Case User Hiroshi subscribes to Petri No auth policy in place, generates a winfo NOTIFY to Petri Petri needs to be able to set authorization decision for Hiroshi Want to be able to set such policies outside of a subscription as well Subscribe Petri Read List Write List Data Manipulation Server Client Standard Ifaces winfo


Hard State Presence Management: Hard State Presence Management Hiroshi subscribes to Petri Petri has been offline for weeks Server sends NOTIFY with current presence state Petri wants to control default state when offline Set it to andlt;activityandgt;vacationandlt;/activityandgt; Subscribe Petri Read PIDF Write PIDF Data Manipulation Server Client Standard Ifaces Notify


Functional Requirements: Functional Requirements Create resource list/auth policies/default presence doc Associate resource list/auth policies/default presence doc with URI Have client define URI Have server assign URI Modify contents of resource list/auth policies/default presence doc Extend resource list/auth policies/default presence doc in hierarchical way Delete a piece of resource list/auth policies/default presence doc Fetch current resource list/auth policies/default presence doc Allow multiple clients to access and modify a shared resource list/auth policies/default presence doc


Performance Requirements: Performance Requirements Protocol will be used on wireless air interfaces Means that it is unacceptable to push the entire resource list/auth policies/default presence doc when a change is needed Unacceptable to get the entire resource list/auth policies/default presence doc when the client needs to look at it Implies local cache Pushing and pulling partial pieces of the data is essential Invalidation of cached data Synchronization of data


Key Observations: Key Observations Clearly a general problem here Allowing a user to managed provisioned data that is accessed by a network application Apply some basic design principles Separate protocol machinery from data schema Don’t box yourself into a corner with the data schema Bandwidth efficiency important Lower the deployment bar This is a well-trod space LDAP, ACAP, SNMP, relational DB cover related spaces, none successfully deployed to broad end client bases


XCAP Architecture: XCAP Architecture Same as previous pictures Scope limited to client to XCAP server Access from Network App could be XCAP Acts as a client There may be no network app XCAP server is repository for client data Network App Not Standardized XCAP Server Client XCAP Not Standardized


The Big “Aha”: The Big 'Aha' XCAP is about clients getting, deleting and putting pieces of hierarchically organized data Ideally XCAP should leverage technologies widely found in phones, PCs and other client devices XCAP can just BE HTTP, by defining the URI hierarchy to extend into 'web documents' HTTP URIs can represent any resource Don’t need to exist on a disk Interpretation is up to the server XCAP defines that interpretation


HTTP in Brief: HTTP in Brief Clients invoke methods on server GET – retrieve content PUT – place content POST – pass data to a process HEAD – get meta-data, not content OPTIONS – query server for capabilities DELETE – remove a resource from a server Requests and responses contain bodies


Fetch a document: Fetch a document andlt;fooandgt; andlt;bar attr='1'andgt;Hiandlt;/barandgt; andlt;bar attr='2' bool='y'andgt;Howandlt;/barandgt; andlt;movie stuff='LOTR'andgt;Areandlt;/barandgt; andlt;/fooandgt; GET http://server.com/dir/foo HTTP/1.1 HTTP/1.1 200 OK Content-Type: application/xml Content-Length: … andlt;fooandgt; andlt;bar attr='1'andgt;Hiandlt;/barandgt; andlt;bar attr='2' bool='y'andgt;Howandlt;/barandgt; andlt;movie stuff='LOTR'andgt;Areandlt;/barandgt; andlt;/fooandgt;


XCAP Scope: XCAP Scope Application Usages Details how you use XCAP for a new app (i.e., CPCP) Server assigned data Naming convention for URIs Document selector – picks the 'XML Document' based on a defined document hierarchy Component selector – picks an element or attribute within the document Using GET, PUT and DELETE for management of elements and attributes Error content Extensibility of data Etag advice


Application Usage: Application Usage Defines what an application needs to do to be used with XCAP Define an Application Unique ID Define the XML Schema for the data Define data semantics Specify naming conventions – binding between application and XCAP Data interdependencies (aka server computed data) Authorization policies


AUID: AUID Unique Identifier for each application Two sub-namespaces IETF tree: tokens in RFC documents IANA Registry Vendor tree: proprietary data Start with reverse DNS name of enterprise Examples IETF Tree 'resource-lists' draft-ietf-simple-xcap-list-usage 'pidf-manipulation' draft-isomaki-simple-xcap-pidf-manipulation-usage-00 'rules' draft-rosenberg-simple-rules Vendor Tree 'com.example.customer-list'


AUID Grammar: AUID Grammar AUID = global-auid / vendor-auid global-auid = auid auid = alphanum / mark vendor-auid = rev-hostname '.' auid rev-hostname = toplabel *( '.' domainlabel ) domainlabel = alphanum / alphanum *( alphanum / '-' ) alphanum toplabel = ALPHA / ALPHA *( alphanum / '-' ) alphanum


Naming Conventions: Naming Conventions An app will have 'hooks' into XCAP Points of operation of application when XCAP is used Need to define how that is done Example: Presence List Fetch document whose uri attribute of andlt;resource-listandgt; is equal to request URI of SUBSCRIBE Example: Authorization Fetch authorization policy documents underneath http://server.com/rules/users/andlt;usernameandgt; where username identifies the presentity


Data Interdependencies: Data Interdependencies In many cases a user defines all of their own data PIDF manipulation usage Authorization policies In some cases a few pieces of it are 'filled in' by the server Resource list URIs for lists – need to be unique, can be server assigned Client can also define them Application usage specifies what pieces server fills in, and how


Modeling Server Computed Data: Modeling Server Computed Data Think of the application usage as a client of XCAP Handset puts a new resource list, URI not present (1) Application learns of change (4) Acting as a client, application modifies data, setting URI (5) This is a model, not an implementation requirement Impacts Etag usage (later)


Authorization Policies: Authorization Policies Who is allowed to access (R/W) XCAP data? Application specific Policies are specified by application usage XCAP defines a 'default' A user can read and write their own data A user can only access their own data Global data is readable by everyone, writeable by no one except privileged users


Definition Example: Definition Example Basic address book from before Would author an RFC structured as follows


Document Contents: Document Contents AUID Want this to be global Pick an appropriate AUID address-book Add an IANA Considerations section registering the AUID XML Schema Include it IANA registry for schema and namespace Naming Conventions No server app No naming conventions No data interdependencies Default authorization policy


Semantics: Semantics An address book is a series of andlt;entryandgt; elements Each andlt;entryandgt; is information about an entry in the address book It has a andlt;nameandgt;, which is the use persons first and last name It has an andlt;emailandgt; element, which contains the email address of the person It has a andlt;postalandgt; element that has the postal address


The Document Hierarchy: The Document Hierarchy XCAP defines URIs as two parts Document selector – chooses the XML document Node selector – chooses the XML component (element, attribute) XPath subset discussed previously XML documents organized into a mandatory hierarchy Borrows from ACAP concepts


Hierarchy Structure: Hierarchy Structure Top is the Root Services URI Identifies start of XCAP tree http://server.example.com/xcap-root http://www.example.com/docs/xml/ietf/xcap/root Next is the AUID Next is 'users' or 'global' 'users' are for per-user documents 'global' are for data that is not user specific – for reading by all users of the app Within users, next is username Underneath username is anything Eventually leads to document


The Hierarchy: The Hierarchy Root services AUID 1 AUID 2 users global petri hiroshi doc1 dir1


Example 1: Example 1 http://xcap.example.com/address-book/users/petri/adbook1/address-book/entry/name andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;emailandgt;jdrosen@dynamicsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt; adbook1


Client Operations: Client Operations Retrieving Document Element Attribute Deleting Document Element Attribute Modifying Document Element Attribute Adding Document Element Attribute KEY CONSTRAINT Can only affect one element, attribute or document at a time


Fetching a Document: Fetching a Document GET http://xcap.example.com/address-book/users/petri/adbook1 HTTP/1.1 HTTP/1.1 200 OK Content-Type: application/adbook+xml Content-Length: … andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;emailandgt;jdrosen@dynamicsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt; andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;emailandgt;jdrosen@dynamicsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt; adbook1


Fetching an Element: Fetching an Element GET http://xcap.example.com/address-book/users/petri/adbook1/ address-book/entry/name HTTP/1.1 HTTP/1.1 200 OK Content-Type: application/xml-fragment-body Content-Length: … andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;emailandgt;jdrosen@dynamicsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt; adbook1


Fetching an Attribute: Fetching an Attribute GET http://xcap.example.com/address-book/users/petri/adbook1/ address-book/entry/street/@paved HTTP/1.1 HTTP/1.1 200 OK Content-Type: application/xml-attribute-value Content-Length: … true andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;emailandgt;jdrosen@dynamicsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt; adbook1


Delete a Document: Delete a Document DELETE http://xcap.example.com/address-book/users/petri/adbook1 HTTP/1.1 HTTP/1.1 200 OK andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;emailandgt;jdrosen@dynamicsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt; adbook1 NULL


Deleting an Element: Deleting an Element DELETE http://xcap.example.com/address-book/users/petri/adbook1/ address-book/entry/name/email HTTP/1.1 HTTP/1.1 200 OK andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;emailandgt;jdrosen@dynamicsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt; adbook1 andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt;


Deleting an Attribute: Deleting an Attribute DELETE http://xcap.example.com/address-book/users/petri/adbook1/ address-book/entry/name/postal/street/@paved HTTP/1.1 HTTP/1.1 200 OK andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;emailandgt;jdrosen@dynamicsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt; adbook1 andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;postalandgt; andlt;streetandgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt;


Modify vs. Add: Modify vs. Add Modify and Add look the same PUT Request Body contains content Behavior depends on URI Server checks if resource exist URI resolves to an existing doc, element in a doc, or attribute in an element If not, the operation is add New content is added such that URI now resolves to the content in the body Schema constraints are obeyed Otherwise inserted after all siblings If so, the operation is modify New content replaces the content selected by the URI


Insert an Element: Insert an Element PUT http://xcap.example.com/address-book/users/petri/adbook1/ address-book/entry/phone HTTP/1.1 Content-Type: application/xml-fragment-body andlt;phoneandgt;+19739525000andlt;/phoneandgt; HTTP/1.1 200 OK andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;emailandgt;jdrosen@dynamicsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt; adbook1 andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;phoneandgt;+19739525000andlt;/phoneandgt; andlt;emailandgt;jdrosen@dynamicsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt;


Modify an Element: Modify an Element PUT http://xcap.example.com/address-book/users/petri/adbook1/ address-book/entry/name HTTP/1.1 Content-Type: application/xml-fragment-body andlt;nameandgt;Jonathan D. Rosenbergandlt;/nameandgt; HTTP/1.1 200 OK andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;emailandgt;jdrosen@dynamicsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt; adbook1 andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-bookandgt; andlt;!—This guy is a bozo -- andlt;entryandgt; andlt;nameandgt;Jonathan D. Rosenbergandlt;/nameandgt; andlt;emailandgt;jdrosen@dynamicsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt;


Server Error Handling: Server Error Handling Server error handling is specified in HTTP specification Most XCAP-specific cases are details within 404 or 409 409 (Conflict) The request could not be completed due to a conflict with the current state of the resource. 404 (Not Found) The server has not found anything matching the Request-URI. XCAP Specific error cases Result of operation results an a document that is not well-formed or valid (409) Resource identified in a request corresponds to multiple elements or attributes (409) Application usage not understood (409) Document, element or attribute does not exist (404) Client provided data that violates a uniqueness requirement (409) Request did not contain valid xml-frag-body (409?)


Conveying Conflict Details: Conveying Conflict Details HTTP recommends including a 409 body detailing problem so client can retry XCAP defines an XML body format for response application/xcap-error+xml MIME type Root element andlt;xcap-errorandgt; Child is specific to the error Detailed error information can be dependent on the error Defined errors match ones on previous slide


URI Exists Error: URI Exists Error Client attempts to set a URI with a uniqueness constraint, and the value exists already Happens in resource lists Server error response indicates URI(s) which had this problem Optional suggested alternates andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;xcap-error xmlns='urn:ietf:params:xml:ns:xcap-error'andgt; andlt;uri-existsandgt; andlt;exists uri='sip:friends@example.com'andgt; andlt;alt-uriandgt;sip:friends2@example.comandlt;/alt-uriandgt; andlt;/existsandgt; andlt;/uri-existsandgt; andlt;/xcap-errorandgt;


Handling Multiple Writers: Handling Multiple Writers Synchronization problems occur when multiple clients can manipulate the same document Especially true when a client needs to do multiple HTTP operations to affect a change XCAP provides no lock But we want to detect this condition and recover Common problem


Solution: Etags: Solution: Etags ETag from HTTP Entity tags are used for comparing two or more entities from the same requested resource. An entity tag MUST be unique across all versions of all entities associated with a particular resource. What does this mean? ETag is a version identifier for a resource Server assigns the etag It changes every time the resource changes


How are they used?: How are they used? HTTP defines several conditional headers If-Match: only process this request if the entity tag matches that held by the server If-None-Match: only process this request if the entity tag does not match If-Range: asks for the byte range that has changed Server returns 412 if condition fails


Example Revisited: Example Revisited User A has version ABC Adds buddy, adds If-Match: ABC Buddy added, new version DEF User B also has version ABC Tries to modify it, but it fails B can now fetch it and make its diff against the current version


Data Extensibility: Data Extensibility XCAP servers MUST understand the application usages they manage They don’t need to understand any namespaces but the root ones Document extensions don’t need to be understood Sometimes, an extension requires the server to understand Setting a URI Guaranteeing Uniqueness


Current Solution: Current Solution Defines a 'mandatory-ns' element This attribute is present as a child of the root element in any document Indicates what namespaces are mandatory andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;address-book xmlns:conf='urn:ietf:2233'andgt; andlt;mandatory-nsandgt; andlt;nsandgt;urn:ietf:2233andlt;/nsandgt; andlt;/mandatory-nsandgt; andlt;!—This guy is a bozo --andgt; andlt;entryandgt; andlt;nameandgt;Jonathan Rosenbergandlt;/nameandgt; andlt;emailandgt;jdrosen@dynamicsoft.comandlt;/emailandgt; andlt;postalandgt; andlt;street paved='true'andgt;600 Lanidex Plandlt;/streetandgt; andlt;cityandgt;Parsippanyandlt;/cityandgt; andlt;stateandgt;NJandlt;/stateandgt; andlt;countryandgt;USAandlt;/countryandgt; andlt;/postalandgt; andlt;conference-uri/andgt; andlt;ietf-participant/andgt; andlt;/entryandgt; andlt;/address-bookandgt;


Presence Authorization: Presence Authorization Specified as a ruleset Each ruleset is a series of rules Each rule has three parts Condition – does this rule apply? Action – what do you do if it does? Transformation – how do you restrict the data seen by a requestor?


Permission Model: Permission Model Each action or transformation is called a permission A permission is a positive grant of information There can never be negative grants, i.e., 'don’t send information X' If there is no permission for something, you get nothing Implication is that the system is privacy safe


Privacy Safe: Privacy Safe If a server doesn’t understand a permission, less information is sent than desired, never more If a server cannot obtain a rule from a remote source, less information is sent than desired, never more No network failures or other transient problems can result in more information being sent than is desired


Common Policy: Common Policy draft-ietf-geopriv-common-policy Defines framework Defines common elements in all systems andlt;identityandgt; - condition matching based on user identity andlt;sphereandgt; - condition based on your presence status andlt;validityandgt; - time range


Current Presence Authorization Elements: Current Presence Authorization Elements Extends the set defined in common-policy with presence-specific data New conditions andlt;anonymousandgt; - is the subscription anonymous Actions andlt;accept-subscriptionandgt; - accept the presence subscription andlt;provide-presenceandgt; - polite blocking or not Transformations andlt;show-namespaceandgt; - provide elements from a specific namespace andlt;show-tupleandgt; - provide elements from specified tuples andlt;show-elementandgt; - provide elements with a specific name


Slide68: andlt;?xml version='1.0' encoding='UTF-8'?andgt; andlt;cr:ruleset xmlns='urn:ietf:params:xml:ns:pres-rules' xmlns:cr='urn:ietf:params:xml:ns:common-policy' xmlns:rpid='urn:ietf:params:xml:ns:rpid' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'andgt; andlt;cr:rule id='1'andgt; andlt;cr:conditionsandgt; andlt;cr:identityandgt; andlt;cr:uriandgt;user@example.comandlt;/cr:uriandgt; andlt;/cr:identityandgt; andlt;/cr:conditionsandgt; andlt;cr:actionsandgt; andlt;accept-subscriptionandgt;trueandlt;/accept-subscriptionandgt; andlt;provide-presenceandgt;trueandlt;/provide-presenceandgt; andlt;/cr:actionsandgt; andlt;cr:transformationsandgt; andlt;show-namespaceandgt; andlt;nsandgt;urn:ietf:params:xml:ns:rpidandlt;/nsandgt; andlt;/show-namespaceandgt; andlt;show-elementandgt; andlt;basic-elements/andgt; andlt;elandgt;rpid:placetypeandlt;/elandgt; andlt;/show-elementandgt; andlt;/cr:transformationsandgt; andlt;/cr:ruleandgt; andlt;/cr:rulesetandgt;