Re: SDshare push

Here is my proposed specification. It seems like this should be fairly easy to implement for anyone who has implemented ordinary SDshare. I tried to keep it as brief and simple as possible. If people like it I can fix up the style a bit and add it to the official spec between the current sections 5 and 6.

Any and all feedback is welcome.


SDSHARE PUSH
============

SDshare push is a form of the SDshare protocol in which the source of
changes pushes them to the recipient, instead of the recipient polling
the source.

This specification only defines the effect of pushing a set of changes
to a recipient, and does not define when pushing happens, nor how
changes are grouped into sets for pushing.


The endpoint
------------

An SDshare push endpoint is simply a URL. There are no requirements on
the form of this URL. To push a set of changes, the source packages
the changes as an Atom feed, then POSTs this feed to the endpoint URL.


The payload
-----------

The payload is an SDshare fragment feed as described in section 5.3.4
of the SDshare specification, with one major difference. Instead of
using atom:link elements to refer to the fragments, the feed includes
the fragments inline using atom:content elements.

The example feed given in section 5.3.4 would thus look as follows
when POSTed using SDshare push:

<?xml version="1.0"?>
 <feed xmlns="http://www.w3.org/2005/Atom" 
       xmlns:sdshare="http://www.egovpt.org/sdshare"
       xmlns:xtm="http://www.topicmaps.org/xtm/">
   <title>Change fragments from the eGovernment Resources
          Topic Map</title>
   <author>
     <name>SDShare Server</name>
   </author>
   <updated>2008-07-17T15:47:17.062211Z</updated>
   <id>28C5DBD8-652A-4617-8C4A-C0FFC49B4475</id>
   <sdshare:ServerSrcLocatorPrefix>http://psi.networkedplanet.
   com/</sdshare:ServerSrcLocatorPrefix>
   <link rel="self"
         href="http://sdshare.networkedplanet.com/
               topicmaps/egov/fragments"/>

   <entry>
     <title>ISO 19115:2003 Geographic Information -
            Metadata</title>
     <updated>2008-07-17T15:55:21.971145Z</updated>
     <id>69CD5264-DB78-49c1-A7E4-04EECFA0AA85</id>
     <content type="application/x-tm+xml;version=1.0">
       <xtm:topicMap version="2.0">
         <xtm:topic id="iso-19115-2003">
	   <xtm:subjectIdentifier href="http://psi.egovpt.org/standard/ISO+19115
              %3A+Geographic+Information+-+Metadata"/>
	   <xtm:name>
	     <xtm:value>ISO 19115:2003 Geographic Information -
                        Metadata</xtm:value>
	   </xtm:name>

	   <!-- ... more information here ... -->

	 </xtm:topic>
       </xtm:topicMap>
     </content>
     <sdshare:TopicSI>http://psi.egovpt.org/standard/ISO+19115
    %3A+Geographic+Information+-+Metadata</sdshare:TopicSI>
   </entry>

   <!-- an entry follows for each fragment being pushed -->
 </feed>

The contents of the individual entries are produced using the
algorithm given in section 5.3.5 of the SDshare specification for
Topic Maps and 5.5.1 for RDF.


The update algorithm
--------------------

The effect of applying an entry within a POSTed SDshare fragment feed
is the same as if the recipient were to download it using normal
SDshare. Thus, the fragment update algorithms in 5.4.4 and 5.5.2 apply
equally to SDshare push.


The server response
-------------------

The server must produce an ordinary HTTP response, with a status code
indicating the outcome of applying the feed. 200 is used to indicate
no failure, while 500 is used to indicate that there was an error.

If there is an error applying a specific fragment, the server's 500
response should have a content-type of "text/plain" and the content of
the response should be the value of the <id> element of the <content>
element wrapping the fragment.

Note that servers may apply fragments asynchronously. In this case,
once the asynchronous thread applying fragments fails, all POST
attempts will result in a 500 response until the error is resolved.
All responses will thus contain the same ID, and it is possible for a
POST request to receive an ID which is not from the feed POSTed, but
from an earlier feed, possibly POSTed by another source.


Suggested usage
---------------

If a source wishes to keep a recipient up to date with changes to a
local collection it should track changes and at intervals POST an Atom
feed to the recipient with all new changes since the previous Atom
feed was POSTed.

It is the responsibility of the source to keep track of what has been
POSTed and what has not.

--Lars M.
http://www.garshol.priv.no/tmphoto/
http://www.garshol.priv.no/blog/