[Protocol] Strawperson Principles and Approach

While we collect use cases, I think it's still fruitful to discuss a
baseline set of interactions that can be refined and extended in response
to the requirements analysis down the line.

As a strawperson to start from, I would like to kick it off by proposing
the following principles and high level design.

== Principles ==

1.  Interactions should be designed to take place over HTTP, but should not
prevent their implementation over other low level protocols, potentially
via some extension.

2.  Interactions should follow the REST best practice guidelines when there
is a resource being acted upon.

3.  We must respect the web architecture first and foremost, seek to re-use
existing systems when possible, collaborate with other working groups if
our requirement falls under their charter, and invent only as a last resort.

4.  Simplicity and ease of use are important but are ultimately subjective
and should not sway us to ignore the above principles other than in extreme
cases.


== Strawperson ==

* Creation, Updating, Retrieval and Deletion of individual annotations
should use the patterns described in the Linked Data Platform API [1].  LDP
is currently in last call, and hence will shortly be a stable base on which
to build.  It follows the web architecture and REST principles, and
mandates the use of JSON-LD which we also require.

In particular, you create an annotation by POSTing to a container URI [2]
with the body of the message containing the JSON-LD serialized annotation.
You update an Annotation by PATCHing with the changes, or PUTing the
complete representation.  ETags should be used by both client and server to
avoid race conditions.

The container that is POSTed to is an LDP construction that holds resources
and allows its contents to be listed.

* Further clarifying the LDP specification, we recommend that the Creation
and Updating operations (PUT, POST, PATCH) as well as retrieval (GET)
return the annotation as modified by the operation in the entity-body.

* We would engage with the LDP WG on the topic of authentication and
authorization, and try to implement any mutually agreeable solution.  The
current web ACL solution [3,4] is incomplete and not standardized, but is
up for discussion in the current rechartering [5] process.

* Notification would be done using ActivityStreams from the Social Web WG
[6].  We would follow the basic approach of <agent>
<created/updated/deleted> <annotation>, rather than attempting to map all
of the properties of the annotation into the notification.  There were
difficulties with annotations such as bookmarks or highlights that do not
have a body in trying to do that mapping [7], for example.

* Search ... well... how about that local sports team, eh? Didn't they do
well? Note, this is not the strawperson you're looking for.  Which is to
say I'd prefer to discuss the above first and keep search for its own
thread :)


References:

[1]  http://www.w3.org/TR/ldp/
[2]  http://www.w3.org/TR/ldp/#ldpc
[3]  http://www.w3.org/2012/ldp/wiki/AccessControl
[4]  http://www.w3.org/wiki/WebAccessControl
[5]  https://www.w3.org/2012/ldp/wiki/LDPNext2015_Charter
[6]  http://www.w3.org/TR/activitystreams-core/
[7]  http://lists.w3.org/Archives/Public/public-annotation/2014Oct/0121.html


-- 
Rob Sanderson
Information Standards Advocate
Digital Library Systems and Services
Stanford, CA 94305