Here is the good news! We are opening up our API and we are very excited about it.

The new API give you programmatic access to Iterations, Stories and Comments for your project. We’ve worked hard at putting together high quality documentation. I’ll put out a few examples here to highlight how the API works.

All methods require authentication before we’ll hand over your precious data (we very much care about the privacy and safety of your data). We provide authentication via a token which must be supplied in the HTTP request. You can find your token on the account setting page.

Projects

Available methods:

• Get all project for the current user
• Get a single project for the current user

When a project is requested basic information such as the iteration sizes and title are returned. Also included in the returned payload is a list of users who are members of the project.

e.g. curl -H "X-AgileBench-Token: TOKEN" -H "Content-type: application/json" http://agilebench.local/api/v1/projects/477

{
    "confidence_tolerance": 20,
    "created_at": "2010-04-05T00:00:00Z",
    "estimate_values": "1,2,3,5,8,unestimated",
    "id": 477,
    "iteration_size_unit": "week",
    "iteration_start_day": "Monday",
    "iteration_unit": 2,
    "title": "Art Social Networking Site (DEMO)",
    "uri": "/projects/477-art-social-networking-site-demo",
    "users": [
        {
            "id": 6704,
            "login": "max",
            "role": "Owner",
            "state": "active",
            "uri": "/projects/477-art-social-networking-site-demo/users/6704"
        },
        {
            "id": 6705,
            "login": "kit",
            "role": "Collaborator",
            "state": "active",
            "uri": "/projects/477-art-social-networking-site-demo/users/6705"
        },
        {
            "id": 6706,
            "login": "sidney",
            "role": "Collaborator",
            "state": "active",
            "uri": "/projects/477-art-social-networking-site-demo/users/6706"
        }
    ],
    "velocity": 13
}

Iterations

Available methods:

• Get an iteration (standard iteration, current iteration or backlog)
• Get all iterations for a project

Let’s say you would like to get a list of stories in your backlog.
e.g.
curl -H "X-AgileBench-Token: TOKEN" -H "Content-type: application/json" http://agilebench.local/api/v1/projects/{project_id}/backlog

Which will return the backlog and the stories within the backlog:

{
    "id": 1324,
    "position": 1,
    "project_id": 477,
    "stories": [
        {
            "blocked": false,
            "comments_count": 0,
            "created_at": "2010-06-14T00:00:00Z",
            "estimate": "5 points",
            "label": 44,
            "position": 1,
            "story_type": "story",
            "title": "As a site owner I want to charge users for an account",
            "updated_at": "2010-06-14T00:00:00Z",
            "uri": "http://agilebench.local/projects/477-art-social-networking-site-demo/stories/44",
            "workflow_state": "todo"
        },
        ...
    ],
    "title": "Backlog",
    "uri": "http://agilebench.local/projects/477-art-social-networking-site-demo/backlog",
    "workflow_state": "todo"
}

Stories

Available methods:

• Get a story
• Get all stories for an iteration
• Update a story

Let’s say you would like to update a story
e.g.
curl -X PUT -H "X-AgileBench-Token: TOKEN" -H "Content-type: application/json" http://agilebench.local/api/v1/projects/{project_id}/stories/{story_id} -d '{"estimate":"1 point","workflow_state":"in_progress"}'

Which will return the updated story:

{
    "blocked": false,
    "comments_count": 0,
    "created_at": "2010-06-14T00:00:00Z",
    "estimate": "1 point",
    "label": 15,
    "position": 1,
    "story_type": "story",
    "title": "As a site owner I want to create a blog",
    "updated_at": "2010-10-25T20:09:07Z",
    "uri": "http://agilebench.local/projects/477-art-social-networking-site-demo/stories/15",
    "workflow_state": "in_progress"
}

There are a couple of differences here from the backlog request we showed before. Firstly we’ve had to specify the PUT HTTP verb to signify we are updating a resource. We also have to provide the data required to update the story, in this case we’re updating the estimate and we’re transitioning the story to being “in progress” from todo. A list of the attributes that can be updated can be found in the “API docs”|http://agilebench.com/api/.

It’s also worth noting that stories don’t have an id, they have a label as their primary key (which is namespaced by the project id).

Comments

Available methods:

• Get all comments for an story
• Create a new comment

Let’s say you would like to create a comment on a story
e.g.
curl -X POST -H "X-AgileBench-Token: TOKEN" -H "Content-type: application/json" http://agilebench.local/api/v1/projects/{project_id}/stories/{story_id}/comments -d '{"text": "Here is my comment"}'

Which will return the newly created comment:

{
    "id": 442,
    "text": "Here is my comment",
    "user": {
        "display_name": "Max Bench",
        "uri": "/projects/477-art-social-networking-site-demo/users/6704"
    }
}

We are already using this internally for source code callbacks into Agile Bench.

Why we’re publishing these APIs

We know there are a lot more ideas and energy outside of the Agile Bench walls than inside it. We want to open up our platform and let others make beautiful things happen.

We have more in store. We also would love your feedback and look forward to more API goodness.

The key premise behind the agile movement was that traditional software development approaches (typically termed waterfall approaches) took too long to deliver working software and typically solved the problem identified at the start of a project which was often not the same problem that needed resolving by the time the software was finally delivered.

Agile aimed to deliver software quickly through close collaboration, iterative development, continuous testing and frequent deployment. This meant the “business” could get its hands on working software much sooner, which reduced confusion around what was actually being delivered. The agile banner covers a number of methodologies, these include Scrum, XP, Crystal, DSDM, Evo and others.

All of these methodologies encompass similar principles and are based around the 4 key pillars of the agile manifesto namely:

• Individuals and interactions over processes and tools
• Working software over comprehensive documentation
• Customer collaboration over contract negotiation
• Responding to change over following a plan

Here at Agile bench we love agile because of it’s pragmatic approach to building software. It’s about business benefit, building for the now with an eye on the future, focusing on how our software can make a difference to the bottom line and collaborating with out colleagues instead of creating barriers between departments. It’s about the business benefit we deliver not the job titles we are given.

Here are some links to further reading about agile development:

• www.agilemanifesto.org
• www.agilealliance.org
• www.infoq.com/agile
• www.controlchaos.com
• www.mountaingoatsoftware.com/scrum
• www.agilesoftwaredevelopment.com

Here are some books you may want to read to get started on your agile journey:

• Agile and Iterative Development: A Manager’s Guide – Great for an overview of agile
• Scrum and XP from the trenches – Once you’ve read the books this field guide helps make the theory work in a real environment
• User Stories Applied – How to create and manage requirements