From: Ian Bicking

Subject: API as Atompub

Date: Jun 22, 2009 04:49 PM

When looking at the SeeClickFix API (http://seeclickfix.com/simple_pages/23)
I was reminded a lot of Atompub, and a little bit of the
GData extensions to Atompub.  (I can't find an address to send this feedback
to SeeClickFix)
Tickets in the system would be Atom entries:

<entry xmlns="http://www.w3.org/2005/Atom"
 xmlns:georss="http://www.georss.org/georss"
 xmlns:open311="XXX">
  <title>Ticket opened on May 31, 2009</title>
  <link href="http://311.heresville.org/tickets/1234" />
  <!-- per suggestion:
http://diveintomark.org/archives/2004/05/28/howto-atom-id#tag -->
  <id>tag:311.heresville.org/tickets/1234</id>
  <updated>20093105T20:03:05Z</updated>
  <category term="street" /> <!-- same as a tag -->
  <author>
    <open311:client>Web</open311:client> <!-- might be, like, 311erific.org
 or something -->
  </author>
  <content type="text">There's a pothole here</content>
  <georss:polygon>
       45.256 -110.45 46.46 -109.48 43.84 -109.86 45.256 -110.45
  </georss:polygon>
  <open311:status>open</open311:status>
</entry>

Notably:

* Titles may be generated automatically, and may not be very important, for
some dumb reason they are required in Atom
* Tags go into <category>
* The actual description goes into <content>
* GeoRSS (http://georss.org/simple
) is used for identifying the location.  Maybe it should be better
specified, though, like:

    <open311:problem-location>
      <georss:...>
    </open311:problem-location>

Queries can be done via GData, which includes free text and
category-based queries.

Atompub servers are allowed to rewrite entries on submission.  For
instance, to enforce a limited set of tags.

Limited tags can be shown through an atompub service document, like:

  <categories fixed="yes"
   xmlns="http://www.w3.org/2007/app">
    <atom:category
     scheme="http://311.heresville.org"
     term="road" />
    <atom:category
     scheme="http://311.heresville.org"
     term="graffiti" />
  </categories>

Unfortunately Atompub is quite a bit more difficult to implement than these
APIs, though I think it's kosher to leave out a lot of the non-applicable
functionality.  It does address many of the issues I see with the APIs
themselves.




-- 
Ian Bicking  |  http://blog.ianbicking.org  |
http://topplabs.org/civichacker

Attachments

text.html (text/html) 3.9 kB