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

API endpoints (Swagger)

The API endpoints are now documented with the OpenAPI 3.0 standard used in Swagger. You can access the documentation of the latest version here: https://www.icescrum.com/api. If you use your own server (on-premise) then append /api to its URL to read the corresponding documentation.

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

To provide compatibility with external services, you can use the following aliases as well: x-gitlab-token, x-auth-token. If you cannot control the HTTP header, you can provide the token using icescrum-token query parameter in the URL, however this is less secure and should be avoided if possible.

Permissions

When you use an authentication token, you get all the permissions of the associated user.

Performing an action through the API requires the same role as it would in the UI (e.g. Product Owner, Administrator…), so depending on what you need you may need to adjust the roles (see the roles and permissions documentation).

Similarly, like in the UI some actions will be available only if you enable the corresponding App.

Data format

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

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": ""
}

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 difference between the data you receive and the data you send to iceScrum: 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"
    }
}

Some enumerated fields such as story types are represented as numbers. The correspondance between the types and the associated numbers is provided in the Swagger Schemas.

More details about what you can send and receive is available for each endpoint in the Swagger documentation.

URLs

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.

Variable parts of the URLs described in the Swagger documentation are surrounded by curly brackets.

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.


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