Blogging Roller

JIRA's got a real REST API now:

REST easy with JIRA 5 | Atlassian Blogs: Now that JIRA 5 is out, let’s talk about one of my favorite features of this new release, JIRA’s new REST API. JIRA has supported remote APIs for many years with SOAP, XML-RPC, and JSON-RPC. However, telling developers that you support SOAP (and only SOAP) is like saying that you like writing applications with COBOL — it’s out of style. Today’s cool kids gravitate towards REST. It’s clean, simple, and highly portable across languages and frameworks.

And checkout the nice looking API docs, which look like they were generated by WADL-to-HTML.

An alternative to Atlassian's new API is the recently release Rational OSLC Adapter for JIRA, which allows you to do more sophisticated integrations with JIRA including delegated UIs for issue creation and selection.

Here's a diagram I worked up over the weekend to explain Shindig REST API internals to my team mates. See the Project SocialSite blog for the full story.

One question that came up recently on the Roller mailing lists was how to generate JSON for a Roller blog. Roller 3.0's new rendering system makes it easy to generate just about any representation of your blog, so JSON is no problem at all. In fact, any Roller user can do it via the Roller UI by simply creating a new page template.

For example, what if you wanted to generate a JSON array of blog entries with id, pubTime and title for each entry, like what's shown below: 

  [
    {id:     "roller:open_source_ghetto_at_javaone", 
     pubTime:"2007-01-12 12:57:17.0", 
     title:  "Open source ghetto at JavaOne?"},
    {id:     "roller:iphone_don_t_think_of", 
     pubTime:"2007-01-11 17:43:29.0", 
     title:  "iPhone: don't think of it as a computer"},
    {id:     "roller:iphone_apple_apps_only", 
     pubTime:"2007-01-09 23:06:15.0", 
     title:  "iPhone: Apple apps only?"}
    ... etc...
  ] 

To do that, you can use the Roller Preferences->Template menu to create a page template like so:

  #set($pager = $model.getWeblogEntriesPager())
  #set($map = $pager.getEntries())
  [
  #foreach($day in $map.keySet())
  #set($entries = $map.get($day))   
  #foreach($entry in $entries)
      {id:     "$entry.website.handle:$entry.anchor", 
       pubTime:"$entry.pubTime", 
       title:  "$entry.title"},
  #end
  #end
  ]

The code above is a little tricky because of the way the entry pager returns entries. To make it easy to display entries by day, the $pager.getEntries() method returns entries in a ordered java.util.Hashmap. The map contains lists of entries, one for each day, and the map is keyed by date objects. To get entries out of the pager you must iterate through the day-date keys, get then entry list for each and then iterate through the entries of that day.

If you create the above template and save it with the name "jsontest" your new page will be available at /<bloghandle>/page/jsontest. And because the $pager object understands the standard Roller request parameters date, cat and page you can subset the data by date and category, and you can page through the results. For example:

   /<handle>/page/jsontest?cat=roller - latest entries in category 'roller'
   /<handle>/page/jsontest?cat=roller?page=1 - first page of entries in category 'roller'
   /<handle>/page/jsontest?date=200601  - Entries from January 2006

Try it on my blog: http://rollerweblogger.org/roller/page/jsontest 

In a future post I'll show how to use Roller-generated JSON data in a sophisticated JavaScript widget. I'm working on an example that uses Dojo and specifically the FilteredTable widget to present a pageable table of Roller blog entries.

For more information on Roller page template programming see the docs for the Apache Velocity template language and see the Roller 3.0 Template Author Guide for details on the Roller objects and macros available within Roller templates.