[Rt-commit] [svn] r845 - in RTx-Atom: . lib/RTx
autrijus at pallas.eruditorum.org
autrijus at pallas.eruditorum.org
Thu May 6 11:10:12 EDT 2004
Author: autrijus
Date: Thu May 6 11:10:11 2004
New Revision: 845
Modified:
RTx-Atom/ (props changed)
RTx-Atom/lib/RTx/Atom.pm
Log:
----------------------------------------------------------------------
r4523 at not: autrijus | 2004-05-06T15:09:49.283337Z
* cleaned up the URI space to do away with verb/adverbs,
by confirmation from jesse.
----------------------------------------------------------------------
Modified: RTx-Atom/lib/RTx/Atom.pm
==============================================================================
--- RTx-Atom/lib/RTx/Atom.pm (original)
+++ RTx-Atom/lib/RTx/Atom.pm Thu May 6 11:10:11 2004
@@ -21,16 +21,13 @@
Some example canonical URIs are:
- /Atom/0.3 # FeedURI
- /Atom/0.3/RT-Tickets # FeedURI
- /Atom/0.3/RT-Tickets!add # PostURI (Container)
+ /Atom/0.3 # FeedURI (Container)
+ /Atom/0.3/RT-Tickets # FeedURI (Container)
+ /Atom/0.3/RT-Tickets # PostURI (Container)
/Atom/0.3/RT-Tickets/15 # EditURI (Object)
+ /Atom/0.3/RT-Tickets/15,16,17 # PostURI (ResultSet)
/Atom/0.3/RT-Tickets/15.Subject # EditURI (Property)
- /Atom/0.3/RT-Tickets/15!update # PostURI (Object)
- /Atom/0.3/RT-Tickets/15!comment # PostURI (Object)
- /Atom/0.3/RT-Tickets/15!correspond # PostURI (Object)
- /Atom/0.3/RT-Tickets/15,16,17!update # PostURI (ResultSet)
- /Atom/0.3/RT-Tickets/15/Transactions # FeedURI
+ /Atom/0.3/RT-Tickets/15/Transactions # FeedURI (Container)
A RT-Atom server may also supplies alias URIs. Whenever an user request the
URI, it is redirected to the canonical URL with a I<301 Moved Permanently>.
@@ -57,20 +54,34 @@
EmailAddress => 'autrijus at example.com',
);
- $rt->Groups->search("HasMember='root'")->update(
+ $rt->Groups->search(Members => { Name => 'root' })->update(
Members => { add => $user },
);
And now the actual requests and responses. Note that C<GET> may
be used instead of C<OPTIONS> at any given time.
+Authentication: (The C<Accept> header will be omitted for brevity from
+now on.)
+
HEAD /Atom/0.3
Accept: application/x.atom+xml,*/*
401 Authorization Required
WWW-Authenticate: WSSE realm="localhost", profile="UsernameToken"
- OPTIONS /Atom/0.3/Users!add
+Log in and probe the "Users" collection:
+
+ OPTIONS /Atom/0.3/Users
+ X-WSSE: UsernameToken Username="guest", ...
+
+ 301 Moved Permanently
+ Location: /Atom/0.3/RT-Users
+
+Try again: (The C<X-WSSE> header is generated anew; it will be omitted
+for brevity from now on.)
+
+ OPTIONS /Atom/0.3/Users
X-WSSE: UsernameToken Username="guest", ...
200 OK
@@ -84,12 +95,33 @@
</content>
</entry>
- POST /Atom/0.3/Users!add
+Now create a user. RT-Atom supports two type of payloads for this,
+distinguished by their C<Content-Type> headers. First is AtomEntry:
+
+ POST /Atom/0.3/Users
+ Content-Type: application/x.atom+xml
+
+ <entry>
+ <content type="text/xml" mode="xml">
+ <body Name="autrijus"
+ EmailAddress="autrijus at example.com" />
+ </content>
+ </entry>
+
+Another one is a form post:
+
+ POST /Atom/0.3/Users
+ Content-Type: application/x-www-form-urlencoded
+
Name=autrijus&EmailAddress=autrijus at example.com
+In both cases, the server will return:
+
303 See Other
Location: /Atom/0.3/RT-Users/20
+Now we can learn something about the freshly created user:
+
GET /Atom/0.3/RT-Users/20
200 OK
@@ -103,39 +135,60 @@
</content>
</entry>
- HEAD /Atom/0.3/Groups?query=HasMember%3D'root'&rows=all
+Next we learn something about Groups:
- 200 OK
- Content-Location: /Atom/0.3/RT-Groups/1,2,3,5,8,13
+ OPTIONS /Atom/0.3/Groups
- OPTIONS /Atom/0.3/RT-Groups/1,2,3,5,8,13
+ 301 Moved Permanently
+ Location: /Atom/0.3/RT-Groups
+
+ OPTIONS /Atom/0.3/RT-Groups
200 OK
<entry>
- <link rel="service.post"
- href="/Atom/0.3/RT-Groups/1,2,3,5,8,13!update"
- title="update" />
+ <content type="text/xml" mode="xml">
+ <body Name="" ...>
+ <Members />
+ </body>
+ </content>
</entry>
- OPTIONS /Atom/0.3/RT-Groups/1,2,3,5,8,13!update
+Now we make a query on Groups:
+
+ HEAD /Atom/0.3/RT-Groups?Members-name=root&rows=all
+
+ 200 OK
+ Content-Location: /Atom/0.3/RT-Groups/1,2,3,5,8,13
+
+Before we perform an update on the result set, we again probe
+for its representation:
+
+ OPTIONS /Atom/0.3/RT-Groups/1,2,3,5,8,13
200 OK
<entry>
<content type="text/xml" mode="xml">
- <body ...>
- ...
- <Members add="Members-add"
- remove="Members-remove" />
+ <body>
+ <Members />
</body>
</content>
</entry>
- POST /Atom/0.3/RT-Groups/1,2,3,5,8,13!update
+Finally, the modification and its response:
+
+ POST /Atom/0.3/RT-Groups/1,2,3,5,8,13
+ Content-Type: application/x-www-form-urlencoded
+
Members-add=30
+The server may respond with this:
+
207 Multiple Status
...<status><code>200</code><text>Member added</text>...
+Note that the final 207 response is not yet codified in stone and
+will be replaced as soon as something better is found.
+
=head2 Authentication
The authentication algorithm uses the C<WWW-Authenticate>,
@@ -219,10 +272,11 @@
=head2 Describe - I<OPTIONS [ PostURI | EditURI | FeedURI ]>
-On a container's PostURI, returns the schema of objects acceptable by this
+On a container's I<PostURI>, returns the schema of objects acceptable by this
container.
-On an object's PostURI, returns the schema acceptable by the specified I<verb>.
+On an object's I<PostURI>, returns the schemata acceptable by it,
+differentiated with the C<type> attribute.
On I<EditURI>, returns the schema of the object or the property, which is a
I<GET> without actual contents.
@@ -247,11 +301,11 @@
=head2 Update - I<POST PostURI> (Object)
-Updates an object, using an I<verb> acceptable to that object's class.
+Updates an object.
207: Updated. Body is the status code and messages for each update.
400: Request failed. Body is the error message.
- 404: The specific object is not found, or supports no such verb.
+ 404: The specific object is not found, or supports no such post type.
=head1 LINK DISCOVERY
@@ -264,9 +318,8 @@
follow the link responsible for that operation.
Whenever the client receives an Atom construct, it may look at each
-C<link> tag. The C<title> attribute determines the type of link:
-
- ( MemberName )? ( "!" Verb )? ( "_" backreference )?
+C<link> tag. The C<title> attribute is the member name of the link;
+but if it begins with C<_>, then it is a backlink.
The C<href> attribute is the target URI. The C<rel> attribute determines
the type of the link target:
@@ -293,9 +346,9 @@
<link title="Groups"
rel="service.feed"
href="/Atom/0.3/RT-Groups" />
- <link title="Groups!add"
+ <link title="Groups"
rel="service.post"
- href="/Atom/0.3/RT-Groups!add" />
+ href="/Atom/0.3/RT-Groups" />
The client may then infer the relationships:
@@ -305,13 +358,26 @@
=item $obj->Groups is a I<Container>.
-=item $obj->Groups understands the verb I<add>.
+=item $obj->Groups may be called to C<add> an object inside it.
-=item $obj->Groups->add( key => 'value' ) should be translated to:
+=item $obj->Groups->add( key => 'value' ) should be translated to this:
+
+ POST /Atom/0.3/RT-Groups
+ Content-Type: application/x-www-form-urlencoded
- POST /Atom/0.3/RT-Groups!add
key=value
+Or this:
+
+ POST /Atom/0.3/RT-Groups
+ Content-Type: application/x.atom+xml
+
+ <entry>
+ <content type="text/xml" mode="xml">
+ <body key="value" />
+ </content>
+ </entry>
+
=back
=cut
More information about the Rt-commit
mailing list