XP-Dev.com Documentation

Stories API

This user guide only applies if your account and project is on our new platform, i.e. if your project's URL begins with https://<your-account>.xp-dev.com rather than https://xp-dev.com. If your account is on our old platform, you should be using this user guide instead.

Each Story Object has the following attributes:

Attribute Description
id Unique Story ID
description Story description in Textile
descriptionHtml Story description in HTML
project Project ID that the Story belongs to
iteration Iteration ID that the Story belongs to, will be zero (0) if the Story is in the backlog
displayId Story’s artifact ID
assignedTo List of usernames that the Story’s tasks are assigned to
completed Whether all the Story’s tasks are completed

List All Stories

GET request to https://<your-account>.xp-dev.com/api/v1/stories/project/<project-id>:

curl https://<your-account>.xp-dev.com/api/v1/stories/project/3

Responses will be a list of Story Objects:

[
    {
        "id":2,
        "description":"Users would like to login to our service",
        "completed":false,
        "project": {
            "id": 3
        },
        "assignedTo":["developer"],
        "displayId":3,
        "iteration":null,
        "htmlDescription":"<p>Users would like to login to our service</p>"
    },
    ...
]

Create a New Story

POST request to https://<your-account>.xp-dev.com/api/v1/stories with the following attributes:

Mandatory:

  • description
  • project

Optional:

  • iteration

Example request:

curl -X POST -H 'Content-Type: application/json' -d '{"description":"this is my story description","iteration":0,"project": 3}' https://<your-account>.xp-dev.com/api/v1/stories

Responses will be in the form of a single Story Object

Get a Single Story

GET request to https://<your-account>.xp-dev.com/api/v1/stories/<story-id>. For example:

curl https://<your-account>.xp-dev.com/api/v1/stories/6

Responses will be in the form of a single Story Object

Update a Single Story

PUT request to https://<your-account>.xp-dev.com/api/v1/stories/<story-id> with the following attributes:

Mandatory:

  • description

Optional:

  • iteration

Example request:

curl -X PUT -H 'Content-Type: application/json' -d '{"description":"updated story description","iteration":0}' https://<your-account>.xp-dev.com/api/v1/stories/6

Responses will be in the form of a single Story Object

Delete a Single Story

DELETE request to https://<your-account>.xp-dev.com/api/v1/stories/<story-id>:

curl -X DELETE https://<your-account>.xp-dev.com/api/v1/stories/6

Story Metrics

Each Story-Metrics Object has the following attributes:

Attribute Description
tasks Number of total, completed and remaining tasks
hours Total number of hours estimated, added, remaining and percentage completion

Get Metrics for a Single Story

GET request to https://<your-account>.xp-dev.com/api/v1/stories/metrics/<story-id>:

curl https://<your-account>.xp-dev.com/api/v1/stories/metrics/6

Responses will be an Story-Metrics Object:

{
    "hours":{
        "total":10.0,
        "remaining":9.0,
        "added":7.0,
        "completion":70.0
    },
    "tasks":{
        "total":1,
        "remaining":1,
        "completed":0
    }
}

Feel free to contact us if you need any assistance.