CAP Publishing and Digital Signature support for CAP Alerts

Student :- Nithin Dara
Mentor :- Nuwan Waidyanatha && Gavin Treadgold

Atom discovery

Initial understanding was that a client discovers an atom/rss feed by sending a request for service document. But to which URL does the client has to send a service document in the first place. After reading through rfc, service document contains the list of channels/feeds that the atom is publishing at particular site. After some searching in google revealed that, a website which supports either rss/atom feed has a <link> tag in its html head. E.g the following is the content of head of any blogger homepage.

   <link rel="alternate" type="application/atom+xml" title="XXX - Atom" href="http://XXX.blogspot.com/feeds/posts/default" />
   <link rel="alternate" type="application/rss+xml" title="XXX - RSS" href="http://XXX.blogspot.com/feeds/posts/default?alt=rss" />
   <link rel="service.post" type="application/atom+xml" title="XXX - Atom" href="http://www.blogger.com/feeds/XXX/posts/default" />

In fact, firefox browser displays the feed icon for the webpage which has the link tag. E.g I have created a webpage which contains a link tag pointing to a dummy site link. Firefox displays the feed icon at the end of the address bar.

   
  <link rel="alternate" title="RSS Feed" href="http://www.example.com/rss-feed.xml" type="application/rss+xml" />

I would suggest sahana home page to include similar link tag.

   
   <link rel="alternate" type="application/atom+xml" title="CAP Alerts" href="http://localhost/sahana/index.php?mod=msg&act=feedHome" />

Atom Publishing Protocol

The Atom Publishing Protocol is an application-level protocol for publishing and editing Web Resources using HTTP. First lets take a look at a feed document. Its root contains a feed and depending on the no. of entries, it has many <entry> as child.

 <?xml version="1.0" encoding="utf-8"?>
 <feed xmlns="http://www.w3.org/2005/Atom">
   <title>Example Feed</title>
   <link href="http://example.org/"/>
   <updated>2003-12-13T18:30:02Z</updated>
   <author>
     <name>John Doe</name>
   </author>
   <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id>
   <entry>
     <title>Atom-Powered Robots Run Amok</title>
     <link href="http://example.org/2003/12/13/atom03"/>
     <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
     <updated>2003-12-13T18:30:02Z</updated>
     <summary>Some text.</summary>
   </entry>
 </feed>

It states the four function required for maintaining a web log:

Create a Web entry
Retrieve the list of logs
Update a web entry
Delete a web entry.

Creating a Web Log

Create a Atom entry and POST it to URI of the collection.

  
   <?xml version="1.0"?>
     <entry xmlns="http://www.w3.org/2005/Atom">
       <title>Atom-Powered Robots Run Amok</title>
       <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
       <updated>2003-12-13T18:30:02Z</updated>
       <author><name>John Doe</name></author>
       <content>Some text.</content>
     </entry>

How should the server respond on successful creation of the entry? The server should respond with status code 201. When the Collection responds with a status code of 201, it SHOULD also return a response body, which MUST be an Atom Entry Document representing the newly created Resource. Since the server is free to alter the POSTed Entry, for example, by changing the content of the atom:id element, returning the Entry can be usefulto the client, enabling it to correlate the client and server views of the new Entry. Without a matching Content-Location header, the client MUST NOT assume the returned entity is a complete representation of the created Resource. The following is an example of how a server may respond to the POST request of above entry.

     HTTP/1.1 201 Created
     Date: Fri, 7 Oct 2005 17:17:11 GMT
     Content-Length: nnn
     Content-Type: application/atom+xml;type=entry;charset="utf-8"
     Location: http://example.org/edit/first-post.atom
     ETag: "c180de84f991g8"
     <?xml version="1.0"?>
     <entry xmlns="http://www.w3.org/2005/Atom">
       <title>Atom-Powered Robots Run Amok</title>
       <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
       <updated>2003-12-13T18:30:02Z</updated>
       <author><name>John Doe</name></author>
       <content>Some text.</content>
       <link rel="edit"
           href="http://example.org/edit/first-post.atom"/>
     </entry>

This change has to be reflected to the Collection feed also. Once again observe the body of the server response. (the entry that is newly added) When you create a new entry the server will add some other elements to that entry. What we are interested is in the <link rel=“edit”/> tag which contains the URI. This is the URI with which you can delete, update and retrieve that entry.

       <link rel="edit" href="http://example.org/edit/first-post.atom"/>

Example For CAP scenario

Delete an Entry

To delete a entry, a client sends a DELETE request to its entry URI. E.g If the client wants to delete the above added entry, the client sends a http DELETE request to the URI in the <link rel=“edit” /> tag. For the above case the URI is:

http://example.org/edit/first-post.atom

When the server receives a DELETE reqest, it should delete the corresponding entry from the Collection Feed.

A successful response SHOULD be 200 (OK) if the response includes an entity describing the status, 202 (Accepted) if the action has not yet been enacted, or 204 (No Content) if the action has been enacted but the response does not include an entity.

Updating an Entry

To update an entry first a client issues GET request for the “edit” entry URI & fetch the content. Because the entry present in the the Collection may not be a complete information about that entry, in order to keep the bandwidth down. The client can make changes and then issues http PUT request to the same URI. And corresponding entry file and the collection should be updated with the changes.

If an existing resource is modified,either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.

Retrieving the Collection

Client can retrieve the collection when send a GET request to the Feed URI. The server should send only a partial list so that it doesnt overwhelm the client with a big document. However it should have meta data to find the next entries in the feed. The entries in the list are ordered according to the value present in the <app:edited> tag. It reflects the time when the entry is updated.

   
   <feed xmlns="http://www.w3.org/2005/Atom">
     <link rel="first"
           href="http://example.org/entries/go" />
     <link rel="next"
           href="http://example.org/entries/2" />
     <link rel="last"
           href="http://example.org/entries/10" />
     ...
   </feed>

There are two more things i need to cover, namely Etag and Slug header of http. Etag will ensure the client always has the latest copy of the entry to edit/update the entry. Slug header is means of suggesting a URL for that entry.