Essence of the annotation protocol

I am still trying to capture the essence of the annotation protocol.   I've asked several questions and am not really satisfied with the answers.  (My fault, probably.)  So please indulge me just a bit further.
I have written the following scenario which I think represents that essence of the protocol insofar as my needs are concerned.  Could one (or more) of you (e.g. Rob)  look at this and see if it looks right.  And if it does, would it be useful to add something like this to the document.
__________________________________________________________________________________

Step 1. Making a resource "Annotation-Friendly"
Sue creates a resource http://example.com /sues-resources/resource1<http://example.com%20/sues-resources/resource1> .  She want it to be "annotation-friendly";  that is, she want  to enable annotations on that resource.
She creates an annotation container for the resource:
http://example.com /sues-resources/resource1/annotations/<http://example.com%20/sues-resources/resource1/annotations/>
It advertises itself, as described in 3.1.1.

Step 2. Creating an Annotation Resource
Fred has created and wants to submit an annotation for http://example.com/ sues-resources/resource1<http://example.com/%20sues-resources/resource1>.    He needs to post that annotation to the container, http://example.com/sues-resources/resource1/annotations/  .  But first he needs to discover that URI.   He can do that via a GET or HEAD on the resource, http://example.com/sues-resources/resource1  as described in examples 3 and 4.
Having discovered the container URI , Fred posts the annotation to it (see example 10).   As a result the server:
1.      Creates an annotation resource.
2.      Lists the URI of the created annotation resource in the container.
3.      Returns a  response which includes:
a.      The annotation as submitted.
b.      Aadditional information, for example "annotatedAt".
c.      The URI of the created annotation.
See example 10.

Step 3. Discovering the Annotations
Finally, Lydia, a researcher, discovers resource http://example.com /sues-resources/resource1<http://example.com%20/sues-resources/resource1> and wants to find its annotations.   She first needs to find the URI of its annotation container. She does so in the same manner that Fred did in step 2.  She then does a GET on that URI, and, as seen in example 2, the list of annotation URIs are provided.



Now I realize there is much more complexity to the protocol and this is an oversimplification, but I reiterate, this (if I got it right) captures the essence, for my purposes.
Question:  The protocol also calls for creation of Body and Other containers.  Is it really necessary to expose this in the protocol?
Thanks.
Ray

Received on Tuesday, 31 March 2015 21:24:39 UTC