[Rt-commit] [svn] r815 - in RTx-Atom: . lib lib/RTx
autrijus at pallas.eruditorum.org
autrijus at pallas.eruditorum.org
Mon May 3 03:16:34 EDT 2004
Author: autrijus
Date: Mon May 3 03:16:34 2004
New Revision: 815
Added:
RTx-Atom/lib/
RTx-Atom/lib/RTx/
RTx-Atom/lib/RTx/Atom.pm
Modified:
RTx-Atom/ (props changed)
RTx-Atom/Makefile.PL
Log:
----------------------------------------------------------------------
r4416 at not: autrijus | 2004-05-03T07:16:08.862237Z
* We're using the perl license.
* Initial checking of a draft POD.
----------------------------------------------------------------------
Modified: RTx-Atom/Makefile.PL
==============================================================================
--- RTx-Atom/Makefile.PL (original)
+++ RTx-Atom/Makefile.PL Mon May 3 03:16:34 2004
@@ -7,7 +7,7 @@
RTx('Atom');
author('Autrijus Tang <autrijus at autrijus.org>');
abstract('Atom API for RT');
-license('gpl');
+license('perl');
&WriteAll( check_nmake => 0, sign => 1 );
Added: RTx-Atom/lib/RTx/Atom.pm
==============================================================================
--- (empty file)
+++ RTx-Atom/lib/RTx/Atom.pm Mon May 3 03:16:34 2004
@@ -0,0 +1,189 @@
+package RTx::Atom;
+
+$RTx::Atom::VERSION = '0.01';
+
+1;
+
+=head1 NAME
+
+RTx::Atom - Atom API for RT
+
+=head1 DESCRIPTION
+
+This RT extension implements a XML-based web service interface, based on
+the B<Atom draft specification>, version 0.3.
+
+If you have never heard of Atom,
+L<http://www.atomenabled.org/developers/tutorials/api-quick-guide.php>
+offers a concise introduction.
+
+Please see
+L<http://www.atomenabled.org/developers/api/atom-api-spec.php>
+for definitions of I<FeedURI>, I<EditURI> and I<PostURI> as used in this
+documentation.
+
+The I<AtomFeed> and I<AtomEntry> formats are defined in
+L<http://www.atomenabled.org/developers/syndication/atom-format-spec.php>.
+
+The authentication algorithm is describe in
+L<http://www.xml.com/pub/a/2003/12/17/dive.html>
+with one important exception -- that article assumes the shared
+password between client and server is in plaintext, but RT/Atom
+uses this instead:
+
+ md5_hex(join(':', $username, $realm, md5_hex($password)));
+
+Request methods and response status codes are specified in
+L<http://www.w3.org/Protocols/rfc2616/rfc2616.html>.
+
+=head1 EXAMPLES
+
+=head2 The RT-Atom URI space
+
+XXX - Describe the principal of odd/even depth, verbs and advers here.
+
+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/RT-Tickets/15 # EditURI (Object)
+ /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
+
+=head2 Sample exchange
+
+Create an 'autrijus' user, then add it to all groups that has 'root'
+as member.
+
+First, the B<RT::Client> code:
+
+ my $rt = RT::Client->new('http://guest:guest@localhost/');
+
+ my $user = $rt->Users->add(
+ Name => 'autrijus',
+ EmailAddress => 'autrijus at example.com',
+ );
+
+ $rt->Groups->search("HasMember='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.
+
+ HEAD /Atom/0.3
+ Accept: application/x.atom+xml,*/*
+
+ 401 Authorization Requred
+ WWW-Authenticate: WSSE realm="localhost", profile="UsernameToken"
+
+ OPTIONS /Atom/0.3/Users!add
+ X-WSSE: UsernameToken Username="guest", ...
+
+ 200 OK
+ ...schema data...
+
+ POST /Atom/0.3/Users!add
+ ...<Name>autrijus</Name>...
+ ...<EmailAddress>autrijus at example.com</EmailAddress>...
+
+ 303 See Other
+ Location: /Atom/0.3/RT-Users/20
+
+ GET /Atom/0.3/RT-Users/20
+
+ 200 OK
+ ...<id>rt-fsck.com://some-id</id>...
+
+ HEAD /Atom/0.3/Groups?query=HasMember%3D'root'&rows=all
+
+ 200 OK
+ Location: /Atom/0.3/RT-Groups/(1,2,3,5,8,13)
+
+ OPTIONS /Atom/0.3/RT-Groups/(1,2,3,5,8,13)!update
+
+ 200 OK
+ ...schema data...
+
+ POST /Atom/0.3/RT-Groups/(1,2,3,5,8,13)!update
+ ...<Members><add href="rt-fsck.com://some-id"/></Members>...
+
+ 207 Multiple Status
+ ...<status><code>200</code><text>Member added</text>...
+
+=head1 OPERATIONS
+
+Here is a list of all operatiive I<verbs> supported by this API,
+including their possible response status codes and meanings:
+
+=head2 Search - GET FeedURI
+
+Search for objects within an container.
+
+Possible query parameters: rows, page, query.
+
+If entries are found, the 'Location:' header is set to a ResultSet.
+
+ 200: Success. Body is the result serialized as an AtomFeed.
+ 400: Request failed. Body is error message in text/plain.
+ 404: There is no container matching the specified URI.
+
+=head2 Get - GET EditURI
+
+Retrieve a representation of an object or property.
+
+Possible query parameters: expand
+
+ 200: Success. Body is the serialized item.
+ 400: Request failed. Body is error message in text/plain.
+ 404: There is no object matching the specified URI.
+
+=head2 Put - PUT EditURI
+
+Modifies an object or property with the serialization in the request body.
+
+ 200: Success. Body is the serialized item again.
+ 400: Request failed. Body is error message in text/plain.
+ 404: There is no object matching the specified URI.
+
+=head2 Remove - DELETE EditURI
+
+Remove the specified object.
+
+ 200: Successfully deleted. Body is success message in text/plain.
+ 400: Request failed. Body is error message in text/plain.
+ 404: There is no object matching the specified URI.
+
+=head2 Describe - OPTIONS PostURI | GET PostURI
+
+On a container, returns the schema of objects acceptable by this container.
+
+On an object, returns the schema acceptable by the specified 'adverb'.
+
+ 200: Success. Body is the requested schema.
+ 400: Request failed. Body is error message in text/plain.
+ 404: There is no container matching the specified URI.
+
+=head2 Add - POST PostURI (Container)
+
+Create a new object from the AtomEntry in the request's body.
+
+ 303: Created. The 'Location:' header is set to the new object's
+ EditURI (for subsequent Get/Update). Body is success message.
+ 400: Request failed. Body is error message.
+ 404: There is no container matching the specified URI.
+
+=head2 Update - POST PostURI (Object)
+
+Updates an object, using an 'adverb' acceptable to that object's class.
+
+ 207: Updated. Body is the status code and messages for each update.
+ 400: Request failed. Body is error message.
+ 404: The specific object is not found, or supports no such adverb.
+
+=cut
More information about the Rt-commit
mailing list