REST API – iceScrum

Documentation This documentation applies only to iceScrum v7.
For old iceScrum R6, read the documentation or migrate.

Access all the iceScrum capabilities through its REST web services API

Migration from R6

The main difference compared to the R6 API is authentication. Indeed, the API used to require username / password, which may be unsafe. The new API now uses tokens: in your account, you can create / revoke tokens at will and use them in API calls to authenticate yourself.

The new API capabilities should be at least equivalent, and even more powerful than before. However, URLs have been changed in order to provide a cleaner and more consistent API.

The format of payloads has been changed too to make full use of JSON objects so string nested properties should be expanded. For example, { “task.parentStory.id”: 42 } should be translated to { “task”: { “parentStory”: { “id”: 42 } } } with the new API.

The API doesn’t need to be enabled anymore, but it still requires an explicit action to be enabled since it now requires generating tokens.

Last, the XML format is no longer supported as it entailed a significant overhead while being superseded by JSON in most modern applications.

Authentication

All API calls require authentication. The first step consists in generating a token by opening the corresponding tab in your profile. You have to name the token in order to generate it.

Tokens give full access to your account through the iceScrum API. To use a token to authenticate a request, add x-icescrum-token as an HTTP header.

x-icescrum-token: bezfjoqspo54zefzefe845e58sf

Alternatively, you can provide it using icescrum-token query parameter in the URL, however this can be less secure:

...?icescrum-token=bezfjoqspo54zefzefe845e58sf

Data format

Most iceScrum APIs produces JSON so you must set the Accept request header to application/json in every call.

Here is a sample of JSON data returned by iceScrum:

{
    "class": "Story",
    "id": 23,
    "acceptanceTests_count": 2,
    "acceptedDate": "2017-08-20T00:00:00Z",
    "activities_count": 2,
    "actor": null,
    "affectVersion": null,
    "backlog": {
        "class": "TimeBox",
        "id": 1
    },
    "creator": {
        "class": "User",
        "id": 2,
        "firstName": "Roberto",
        "lastName": "Doe"
    },
    "dateCreated": "2017-09-04T13:22:24Z",
    "dependsOn": null,
    "description": "",
    "doneDate": null,
    "effort": null,
    "estimatedDate": null,
    "feature": {
        "class": "Feature",
        "id": 4,
        "color": "#a0dffa",
        "name": "Search"
    },
    "followers_count": 1,
    "inProgressDate": null,
    "lastUpdated": "2017-09-04T13:22:32Z",
    "name": "Search by physical characteristics",
    "notes": "",
    "origin": null,
    "parentSprint": null,
    "plannedDate": null,
    "rank": 6,
    "state": 2,
    "suggestedDate": "2017-08-19T00:00:00Z",
    "tasks_count": 0,
    "todoDate": "2017-09-04T13:22:24Z",
    "type": 0,
    "uid": 23,
    "value": 0,
    "voters_count": 0,
    "testState": 1,
    "tags": [],
    "dependences": [],
    "followed": true,
    "countDoneTasks": 0,
    "comments_count": 0,
    "attachments_count": 0,
    "commits_count": 0,
    "builds_count": 0,
    "hasVotedFor": false,
    "notes_html": ""
}

Send data

If you send data to iceScrum, in addition to the other headers set the Content-Type header to application/json. Provide your JSON data as the HTTP request body.

There is a significant difference between the data you receive and the data you send to iceScrum. Indeed, you must surround any item by an object with the item type in camel case (starting with a lower-case letter) as a key.

For example, to create a story set the following as your request body:

{
    "story": {
        "name": "this is a test"
    }
}

General rules

Request methods / HTTP verbs

  • DELETE: used to Delete resources
  • GET: used to Get resources
  • POST: used to Create resources
  • PUT: used to Update resources

Response status codes

  • 200: The request has succeeded and data is returned, e.g. Get and Update
  • 201: The request has succeeded, e.g. Create
  • 204: The request has succeeded and no data is returned, e.g. Delete
  • 401: The token is missing or invalid
  • 403: The user doesn’t have necessary permissions to perform the action
  • 4xx: Client error
  • 5xx: Server Error

URL construction

All URLs starts by the URL of your iceScrum server followed by /ws/

http://iceScrumServer/ws/...

Your server URL may or may not end by /icescrum depending on how it is configured, if you have any doubt check how you open it in your browser.

For conciseness, URLs provided below will omit everything before the /ws/ part.

Variable parts of the URLs described in this documentation are preceded by a dollar sign ($). In the following example, $project should be replaced by a project ID or key and $id should be replaced by the Task ID:

/ws/project/$project/task/$id

Enumerated fields

In iceScrum, enumerated fields such as story types are represented as numbers. The correspondance between the types and the associated numbers is provided below:

Release

  • state: 1: todo, 2: in progress, 3: done

Sprint

  • state: 1: todo, 2: in progress, 3: done

Feature

  • state: 0: todo, 1: in progress, 2: done
  • type: 0: functional, 1: architectural

Story

  • state: 1: suggested (sandbox), 2: accepted (backlog), 3: estimated (backlog), 4: planned (sprint), 5: in progress (sprint), 6: in review (sprint), 7: done (sprint), -1: frozen (“all” backlog)
  • type: 0: user story, 2: defect, 3: technical story
  • testState (summary of story’s acceptance tests states): 0: no test, 1: to check, 5: failed, 10: success

Acceptance test

  • state 1: to check, 5: failed, 10: success

Task

  • state: 0: todo, 1: in progress, 2: done
  • type: 10: recurrent, 11: urgent

Project REST Resources

The main iceScrum items (release, sprint, feature, story, acceptanceTest, actor, task, timeBoxNotesTemplate) are available as REST resources. Their URLs require:

  • $project: required, Project ID (integer), or pkey (upper case string)
  • $type: required, item type (String) among: release, sprint, feature, story, acceptanceTest, actor, task, timeBoxNotesTemplate
  • $id: item ID (integer), do not confuse with UID

Here are the two available URL patterns and the corresponding verbs:

/ws/project/$project/$type
  • GET: get all items of type $type for project $project
  • POST: create an item of type $type for project $project
/ws/project/$project/$type/$id
  • GET: get the item of type $type and ID $id for project $project
  • PUT: update the item of type $type and ID $id for project $project
  • DELETE: delete the item of type $type and ID $id for project $project

Comment Resource

Available since 7.14, latest version in 7.38

Comments are available as a REST resource. Its URLs use:

  • $project: required, Project ID (integer), or pkey (upper case string)
  • $id: comment ID (integer)
  • $commentableType:, commentable item type (String) among: story, task, feature
  • $commentableId: commentable item ID (integer), do not confuse with UID

Here are the URL patterns and the corresponding verbs:

/ws/project/$project/comment/$commentableType/$commentableId
  • GET: get all comments on item of type $commentableType and ID commentableId for project $project
/ws/project/$project/comment
  • POST: create a comment for project $project. Expects the commentable id and class as part of the payload: {“comment”: { “body”: “…”, “commentable”: { “id”: …, “class”: “Story” }}}
/ws/project/$project/comment/$id
  • GET: get the comment of ID $id for project $project
  • PUT: update the comment of ID $id for project $project
  • DELETE: delete the comment of ID $id for project $project

User resource

Available since 7.2, deletion since 7.18

Only one endpoint is accessible for users without administration permissions:

/ws/user/current
  • GET: get the current user (the one associated to the token sent by the request)

The full user resource can only be manipulated by an administrator. Here are the two available URL patterns and the corresponding verbs:

/ws/user
  • GET: get all users
  • POST: create a user
/ws/user/$id
  • GET: get the user of ID $id
  • PUT: update the user of ID $id

User deletion is a special case. Indeed, while it may be desirable to delete the projects and teams they have created (see the dedicated option below), it is often not desirable to delete the data they authored on other projects (stories, tasks, comments…). The solution iceScrum offers consists in replacing the authorship of such data by another user. You may create a dedicated user for that, e.g. named “Deleted user”.

/ws/user/$id/replaceBy/$otherUserId
  • DELETE: delete user of ID $id, keep their projects / teams and replace their authorship / ownership by user of ID $otherUserId
/ws/user/$id/replaceBy/$otherUserId?deleteOwnedData=true
  • DELETE: delete user of ID $id, delete their projects / teams and replace their authorship / ownership by user of ID $otherUserId

Other actions

Besides the REST resources presented above, some not so REST actions are also available:

Project

/ws/project/$project/export/$format
  • GET: get the project export in format $format among xml or zip (includes attachments)

Release
Available since 7.2

/ws/project/$project/release/$id/releaseNotes/$timeBoxNotesTemplateId
  • GET: get release notes for release with id $id using notes template with id $timeBoxNotesTemplateId (text/plain)

Sprint
Available since 7.2

/ws/project/$project/sprint/$id/sprintNotes/$timeBoxNotesTemplateId
  • GET: get sprint notes for sprint with id $id using notes template with id $timeBoxNotesTemplateId (text/plain)

History / activities
Available since 7.38

/ws/project/$project/activity/$type/$typeId
  • GET: get all activities on item of type $type (story, feature or task) and ID typeId for project $project
/ws/project/$project/activities
  • GET: get recent story activity for project $project

Version

You can get the iceScrum version in plain text with the following request:

/version

Since iceScrum 7.23, you can also check for new versions with the following request, which returns a JSON object:

/version?verbose=true

Examples

Here are some examples of API calls using the cURL command line tool:

curl -H "Accept: application/json"                         \
     -H "x-icescrum-token: bezfjoqspo54zefzefe845e58sf"    \
     http://mycompany.com/icescrum/ws/project/MYPROJ/story
curl -H "Accept: application/json"                         \
     -H "x-icescrum-token: bezfjoqspo54zefzefe845e58sf"    \
     -H "Content-Type: application/json"                   \
     -d '{ "story": { "name": "foobar" } }'                \
     http://mycompany.com/icescrum/ws/project/MYPROJ/story
curl -H "Accept: application/json"                          \
     -H "x-icescrum-token: bezfjoqspo54zefzefe845e58sf"     \
     -H "Content-Type: application/json"                    \
     -d '{ "task": { "name": "Test", "sprint": { "id": 3 }, "parentStory": { "id": 42 } }, "color": "#808080" }'    \
     http://mycompany.com/icescrum/ws/project/MYPROJ/task


Try it for free now
All you need for your Agile project management