[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: PaceControlResource, PacePubControl, PacePubStatusResource... seeking consensus
On 7/13/05, James M Snell <jasnell@xxxxxxxxx> wrote:
> Ok, just to flesh this out a bit Joe and to make sure I completely
> understand your thinking on this, using the mechanism you describe, how
> would one set control properties for non-Atom resources? e.g. PNG
> files. (I could imagine it for myself but I want to know what you're
> thinking).
There are two ways to do this. The first is by using content
negotiation on the member resource.
=== Using Content Negotiation ===
POST /collection HTTP/1.1
Host: example.org
User-Agent: Cosimo/1.0
Accept: application/atomcoll+xml
Content-Type: image/png
Content-Length: nnnn
Name: trip-to-beach.png
...binary data...
Here, the client is adding a new image resource to a collection. The
Name: header indicates the client's desired name for the resource, see
Section 5.2.6.
Example Response, resource created successfully.
HTTP/1.1 201 Created
Date: Fri, 25 Mar 2005 17:17:11 GMT
Content-Length: nnnn
Content-Type: application/atomcoll+xml; charset="utf-8"
Location: http://example.org/images/trip-to-the-beach-01.png
<?xml version="1.0" encoding="UTF-8"?>
<collection xmlns="http://purl.org/atom/app#";>
<member href="http://example.org/images/trip-to-beach.png";
hrefreadonly="http://example.com/ed/im/trip-01.png";
title="trip-to-beach.png"
updated="2005-03-25T17:17:09Z" />
</collection>
Now I can do a GET on the created member resource, specifying
a preferred type of 'application/atom+xml;form=control'
GET /images/trip-to-beach.png HTTP/1.1
Host: example.org
User-Agent: Agent/1.0
Accept: application/atomcoll+xml;form=control
Which would return an Atom entry with only the control information:
HTTP/1.1 200 OK
Date: Fri, 25 Mar 2005 17:15:33 GMT
Last-Modified: Mon, 04 Oct 2004 18:31:45 GMT
ETag: "2b3f6-a4-5b572640"
Content-Length: nnnn
Content-Type: application/atomcoll+xml;form=control;charset="utf-8"
<entry xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-09";>
<control xmlns="http://example.net/appns/";>
<draft>no</draft>
</control>
</entry>
You can then PUT the same type of document back to the member resource
to update the URI
PUT /images/trip-to-beach.png HTTP/1.1
Host: example.org
User-Agent: Agent/1.0
Content-Length: nnnn
Content-Type: application/atomcoll+xml;form=control
<entry xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-09";>
<control xmlns="http://example.net/appns/";>
<draft>yes</draft>
</control>
</entry>
The other way to accomplish this same task is to include a control URI
in the collection document:
=== Not Using Content Negotiation ===
POST /collection HTTP/1.1
Host: example.org
User-Agent: Cosimo/1.0
Accept: application/atomcoll+xml
Content-Type: image/png
Content-Length: nnnn
Name: trip-to-beach.png
...binary data...
Here, the client is adding a new image resource to a collection. The
Name: header indicates the client's desired name for the resource, see
Section 5.2.6.
Example Response, resource created successfully.
HTTP/1.1 201 Created
Date: Fri, 25 Mar 2005 17:17:11 GMT
Content-Length: nnnn
Content-Type: application/atomcoll+xml; charset="utf-8"
Location: http://example.org/images/trip-to-the-beach-01.png
<?xml version="1.0" encoding="UTF-8"?>
<collection xmlns="http://purl.org/atom/app#";>
<member href="http://example.org/images/trip-to-beach.png";
hrefreadonly="http://example.com/ed/im/trip-01.png";
hrefcontrol="http://example.com/ctl/im/trip-o1.atom";
title="trip-to-beach.png"
updated="2005-03-25T17:17:09Z" />
</collection>
To update the control information you GET the hrefcontrol represenation:
GET /ctl/im/trip-o1.atom HTTP/1.1
Host: example.org
User-Agent: Agent/1.0
Accept: application/atomcoll+xml;form=control
Which would return an Atom entry with only the control information:
HTTP/1.1 200 OK
Date: Fri, 25 Mar 2005 17:15:33 GMT
Last-Modified: Mon, 04 Oct 2004 18:31:45 GMT
ETag: "2b3f6-a4-5b572640"
Content-Length: nnnn
Content-Type: application/atomcoll+xml;form=control;charset="utf-8"
<entry xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-09";>
<control xmlns="http://example.net/appns/";>
<draft>no</draft>
</control>
</entry>
You can then PUT the same type of document back to the member resource
to update the URI
PUT /ctl/im/trip-o1.atom HTTP/1.1
Host: example.org
User-Agent: Agent/1.0
Content-Length: nnnn
Content-Type: application/atomcoll+xml;form=control
<entry xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-09";>
<control xmlns="http://example.net/appns/";>
<draft>yes</draft>
</control>
</entry>
=== Summary ===
Both have their downsides. The first method uses content negotiation
which does have it's drawbacks. The second method increases the size
of the collection document. Pick your poison :)
-joe
>
> - James
>
> Joe Gregorio wrote:
>
> >On 7/12/05, James M Snell <jasnell@xxxxxxxxx> wrote:
> >
> >
> >>The discussion about publication control was left somewhat up in the
> >>air. As these are still marked as "Currently Under Discussion" we need
> >>to see if we can drive some consensus on these. PaceControlResource,
> >>PacePubControl and PacePubStatusResource all approach the problem from
> >>slightly different angles. I intend to update PaceControlResource so
> >>that it fits the profile of an actual proposal with actual proposed spec
> >>text but want to run this by the group first to see if we can come to a
> >>somewhat rough consensus on the concept before working to get consensus
> >>on actual draft language.
> >>
> >>1. Define a new Control document. Media type is
> >>application/atomcontrol+xml.
> >>
> >> <atom:control>
> >> ...
> >> </atom:control>
> >>
> >>
> >
> >Here is an alternative suggestion, consider this entry,
> >which could be POSTed to an entry collection to create a
> >new collection member:
> >
> > <entry xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-09";>
> > <title>Atom-Powered Robots Run Amok</title>
> > <updated>2003-12-13T18:30:02Z</updated>
> > <summary>Some text.</summary>
> > </entry>
> >
> >This has a mime-type of application/atom+xml.
> >Control information could be added to it ala PacePubControl:
> >
> ><entry xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-09";>
> > <title>Atom-Powered Robots Run Amok</title>
> > <updated>2003-12-13T18:30:02Z</updated>
> > <summary>Some text.</summary>
> > <control xmlns="http://example.net/appns/";>
> > <draft>no</draft>
> > </control>
> ></entry>
> >
> >Note that this too has a mime-type of application/atom+xml
> >and can also be POSTed to an entry collection. Now we
> >can create an entry, or create an entry with control information.
> >The only step left is editing the control information in an efficient
> >manner. My suggestion is to use a parameter on the mime-type and
> >content-negotiation to do that efficiently. That is, consider this
> >entry:
> >
> ><entry xmlns="http://purl.org/atom/ns#draft-ietf-atompub-format-09";>
> > <control xmlns="http://example.net/appns/";>
> > <draft>no</draft>
> > </control>
> ></entry>
> >
> >Note that it only has the control information. We could give this document
> >a mime-type of "application/atom+xml;form=control".
> >
> >When you want to edit an entry, but only affect the control information
> >you would do a GET on the entry URI and send an Accept: header
> >of:
> >
> > Accept: application/atom+xml;form=control, application/atom+xml
> >
> >If the server is capable, it will return an entry that only contains the control
> >information, if not, then the full entry with control information will
> >be returned.
> >
> >To update the control information, just PUT the updated document
> >with a content-type of application/atom+xml;form=control.
> >
> >The same cycle of GET and PUT of "application/atom+xml;form=control"
> >can also be used on the collection resource to get/set defaults for the
> >collection.
> >
> >Advantages:
> >
> >1. Let's control information be sent with an entry on creation.
> >2. Allows for efficient updating of control information.
> >3. While you can use this technique on the creation of non-entry
> > collection members, it can be used afterwards to edit the
> > control information on non-entry collection members.
> >
> >Disadvantages:
> >
> >1. Uses content-negotiation.
> >
> >Caveats:
> >
> >1. I'm not wedded to the name 'form=control'. Other suggestions for better
> > parameter names and values are welcome.
> >2. I'm not tied to the idea of using GET/PUT on the collection resource
> > to get/set defaults. It does map nicely, but I haven't thought out all the
> > consequences.
> >
> > Thanks,
> > -joe
> >
> >
> >
>
>
--
Joe Gregorio http://bitworking.org