Dion Moult Seriously who ever reads this description.

Things I should’ve done earlier.

On Linux, there are things that you know are better but you don’t switch because you’re comfortable where you are. Here’s a list of the things I’ve changed the past year that I really should’ve done earlier.

… would be interested to know what else I could be missing out on! :)

Competitive weight loss with WeightRace.net

So last year (or perhaps even the year before, time flies!) two people close to me participated in a friendly weight-loss competition. To do this, they used WeightRace.net.

WeightRace is a small web application I built a while ago for fun, which allows up to four contestants to compete towards a weight goal which they would set. They would be prompted daily for weight updates, and would set a reward for the winner. It also used some lightweight gamification so contestants could earn bonus “wobbly bits” when achieving things like their BMI.

But enough talking about the application — applications are boring! Much more interesting are results! Let’s see:

WeightRace - competitive weight loss

The two contestants — whom we shall refer to as Rob and Julie, which may or may not be their real name — and their results are shown in the graph above. Julie is red, Rob is blue, and their linear trajectories towards their weight goal is shown via the corresponding coloured dotted line.

If I could hear a sped-up commentary of the results, it would truly be exciting! Rob makes an excellent head-start well ahead of his trajectory, whereas Julie is having trouble beginning. As we near the holiday (Christmassy) season, we see Rob’s progress plateauing, whereas Julie gets her game on and updates with a rigorous discipline. Also great to notice is the regular upward hikes in Julie’s weight – those correspond with weekends! As the holidays pass, Rob makes gains and is unable to recover.

In the end, although Julie wins the Race, neither Julie or Rob met their weight goal (note that in terms of absolute figures, Rob actually wins). However, this was all not in vain. Given that almost another year has passed since this race finished, and I can see that Rob’s weight is now well under control and has indeed achieved his goal, I’d like to think that the WeightRace has played a role.

In particular, the WeightRace helped raise daily awareness. I believe that it was this daily awareness of the current weight that helped most in the long-term. In addition, the WeightRace helped Rob’s body to stabilise around 90kg for half a year! I suspect his body figured out that it could manage at that weight, which made it easier for him to (after the WeightRace) continue to lose weight at a healthy pace.

For those interested in playing with the WeightRace, you can check it out online at WeightRace.net. Note though that it is not actually complete, but works good enough for a competition. For those interested in the source, it’s up on my GitHub.

Use Behat to recover your legacy web app

Your legacy project is going to the dogs. No problem, with this easy 7 line code patch you can now fix your entire codebase within a weekend!

/**
 * @Given /^I will write this test in the future$/
 */
public function iWillWriteThisTestInTheFuture()
{
    throw new PendingException();
}

Go you! :)

Architectural visualisation renders with Blender

It’s been a while since I’ve made a post. Although there are posts in the queue, I figured I might post this as it’s a quick one. Let’s see the pictures first.

Visualisation 1

… and the other …

Visualisation 2

Images done with Blender and Cycles. Piano in second render done by RegusTtef. These images are 50% of actual size, together these images took a day and a half. Second image is a panoramic shot.

The building is a proposal for the Sydney Museum of Profligate Steel Welders. The rest writes itself :)

Building REST APIs with auto-discoverable auto-tested code

For the past few months, one of the projects I’ve been working on with SevenStrokes involves building a REST API for a service. REST APIs are tricky things to get right: they’re deceptively simple to describe, yet play host to plenty of interesting topics to delve into. Such topics can be statelessness, resource scope, authentication, hypermedia representation and so on.

However I’m going to only talk about the very basics (which many people overlook), and demonstrate how the Richardson Maturity Model can help with automated testing and documentation. If you haven’t heard of RMM yet, I recommend you stop reading and go through it now (especially if you’ve built a REST-like API before).

Let’s say our REST API conforms to a level 3 RMM: we have a set of standardised verbs, querying logical resources, receiving standardised status codes, and being able to navigate the entire system via links. We’ve got a pretty good setup so far. All these items in the RMM help our REST API system scale better. However what is doesn’t yet help with is keeping our documentation up to date. This is vital, because we know that the holy grail for REST API is an auto-generated, always up-to-date, stylish documentation that promotes your site/product api. There’s a bunch of tools that help you do this right now, but I think they’re all rather half-baked and used as a bolt-on rather than a core part of your application.

To solve this, I’m going to recommend one more addition: every resource must have the OPTIONS verb implemented. When invoked, it will respond with the following:

  1. An Allow header, specifying all the other verbs available on the invoked resource.
  2. A response body, containing the verbs, and under them in the hierarchy of the body (in whatever format), a description of:
    • Their input parameters, including type, and required boolean
    • A list of example requests and responses, detailing what headers, parameters and body are included in the request, and what headers, status code and body is included in the response.
  3. A list of assumptions that are being made for each example scenario (if applicable)
  4. A list of effects on the system for each example scenario (if applicable)
  5. A list of links to any subresources with descriptions

Let’s see a brief example:

# OPTIONS /user/

{
    "GET": {
        "title": "Get information about your user",
        "parameters": {
            "foobar": {
                "title": "A description of what foobar does",
                "type": "string",
                "required": false
            },
            [ ... snip ... ]
        },
        "examples": [
            {
                "title": "View profile information successfully",
                "request": { "headers": { "Authentication": "{usersignature}" } },
                "response": {
                    "status": 200,
                    "data": {
                        "id": "1",
                        "username": "username1",
                        [ ... snip ... ]
                    }
                }
            },
            [ ... snip ... ]
        ]
    },
    [ ... snip ... ]
    "_links": {
        "self": {
            "href": "\/makkoto-api\/user"
        },
        [ ... snip ... ]
    }
}

Sound familiar? That’s right. It’s documentation. Better than that, it’s embedded documentation. Oh, and better still, it’s auto-discoverable documentation. And if that isn’t great enough, it’s documentation identical to the format of requests and responses that API clients will be working with.

Sure, it’s pretty nifty. But that’s not all! Let’s combine this with TDD/BDD. I’ve written a quick test here:

Feature: Discover
    In order to learn how the REST API works
    As an automated, standards-based REST API client
    I can auto-discover and auto-generate tests for the API

    Scenario: Generate all tests
        Given that I have purged all previously generated tests
        Then I can generate all API tests

That’s right. This test crawls the entire REST API resource tree (starting at the top-level resource, of course), invokes OPTIONS for each resource, and generates tests based on the documentation that you’ve written.

Let’s see a quick demo in action.

Auto-documentation for REST APIs in action

It’s a really great workflow: write documentation first, generate tests from it, and then zone in on your tests in detail. This ensure that your code, tests and documentation are always in sync.

I hope someone finds this useful :) For the curious, the testing tool is Behat, and output format used is application/hal+json, using the HAL specification for linking, and link URI templates.

← Back in Time