Practical Hypermedia for our post ORM world

This post is for people who have started learning about hypermedia and feel that it over complicates the elegance of REST. When I started hearing about hypermedia I felt it was adding architecture acrobatics for the sake of buzzword enhancement. After having applied these techniques in a few places not only have a drunk the cool aid, I’ve setup a stand beside my desk. I look back and try to understand where my initial negative reaction came from. I realized that many of the examples were trivial and did not demonstrate the reality of what hypermedia brings to the table.

The main epiphany I’d like to share is that REST has proven itself as the best way to take an ORM focused approach to an API and Hypermedia is proving itself as the best way to take a business process approach to an API.

A key aspect of Hypermedia that I don’t see used often enough is the notion of a template. The template portion of the spec calls for the API to send down to the client the parameters necessary to call the API itself. This notion is akin to how you load a web page with a blank form and then submit the form directly. You don’t post to twitter by typing a bunch of stuff into the url, you load twitter first and then fill in a textarea.

Essentially in my early experiments I was writing XML api payloads where the template portion was basically an HTML form that the client could decompose and render. The problem that I felt was that I was basically writing a full old school web application that happened to send XML rather than HTML back to the client. Then my client had extra complexity in parsing the XML and implementing all the UX rules to get the client looking and feeling right. I also had to build 2 webapps that both were basically doing the same thing, view, validation and calling a service.

Now lets take a look at doing this for real using AngularJS, JSON and a deadline.

Continue reading →

JIRA story point totals using Ruby and Rest

I’m using a hosted version of JIRA and needed to obtain quick totals based on filters that I have setup.

I could not find any easy documentation online so I thought I’d share my quick hack.

The REST API is very well documented and uses the same JQL as the filters do.

In order to view the commit list for an iteration I have some JQL that looks like:

fixversion = 20120611 and fixversion was 20120611 ON "2012/06/11" AND status NOT IN (canceled, "on hold")

In order to feed that into the API I needed to construct a url along the lines of

https://energyplus.atlassian.net/rest/api/2/search?jql=#{urlencoded JQL string}&fields=customfield_10003&maxresults=400

The &fields=customfield_10003 instruct the API to return a minimal fieldlist and only include that custom field, which for me is Story Points.  By default the API will return 50, so bump that to 400 to be safe.

The Ruby code looks like

def getData(api,qs="")
 url = "https://energyplus.atlassian.net/rest/api/2/#{api}?#{qs}"
 res = open(url,
                "Authorization" => "Basic " + 
                  Base64.strict_encode64(USERNAME:PASSWORD)) {|f|
            JSON.parse(f.read)
           })

Calling that function I use something along the lines of

result =  getData("search", "jql=" + URI::encode(jql + '&fields=customfield_10003&maxResults=400'))

The final step is to loop through all the results and sum the ‘Story Point’ values

puts "Total: " + res["issues"].inject(0){|sum, item| sum + item["fields"]["customfield_10003"]}.to_s

If you are having issues with the SSL cert, try adding

OpenSSL::SSL::VERIFY_PEER = OpenSSL::SSL::VERIFY_NONE

Here is my actual script in its undocumented glory: https://gist.github.com/2919437

If you think you can improve it, drop me a note – I’m hiring ;)