Things to know before starting using this API

If you have any problems or if you notice any errors in the documentation, you can contact us on the iceScrum community forum.

Please note that all IDs used in the iceScrum API are technical ones. Don’t confuse them with UIDs.

We recommend you read the following sections before starting using this API. Also, you may want to try a simple curl command to check that the API is enabled and works as expected. Here is an example of a valid curl command that retrieves all the stories of the project YOURPROJ in JSON:

curl -H "Accept: application/json" -u yourUsername:yourPassword \
     --verbose http://yourCompany/icescrum/ws/p/YOURPROJ/story

Configuration

First of all, you need to enable Web Services for your project. Indeed, for security purposes, Web Services are disabled by default.

URL

The iceScrum Web Services API uses URLs with the following structure:

http://:server/ws/p/:pkey/...

Input

:server

Required

:pkey

Required - The unique key of your project

For iceScrum Cloud users, the URL is:

https://www.icescrum.com/a/ws/p/:pkey/...

Authentication and users

All iceScrum API operations need authentication. Credentials have to come with your requests by using HTTP Basic Authentication.

For most operations, it’s recommended choosing the credentials of a user who has PO & SM rights for the project you want to update. This will ensure access to all operations. However, please note that some operations will take the current user into account (“take” on a task will set the current user as the task responsible).

Data format

The iceScrum APIs accept either JSON or XML for input and output data.

For GET requests, you can choose the data format by setting the Accept attribute of your request header:
– JSON: application/json
– XML: application/xml

For PUT or POST requests, define the Content-Type attribute of the request header according to the format of the request body your provide.

Please note that the data format of the body and the response must be the same.

Input data

In the documentation, you will find the required and optional attributes to set for each operation that needs input data. You will have to “convert” them to the chosen format. For example, to plan a story in a sprint, the documentation gives the following input:

Input

story.name

Required integer

The corresponding input data for sprint #25 will be :

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

<story>
    <name>This is a test story</name>
</story>

However, if you use XML, the ID must be provided as an attribute:

<story id="220">
    <name>This is a test story</name>
</story>

Output data

For each operation that returns data, we provide an example response in JSON and XML.

Request methods

DELETE: used for Delete operations
GET: used for Read operations
POST: used for Create and specific operations
PUT: used for Update operations

Response status codes

200: The request has succeeded and data is returned, used for Get, Update and specific operations
201: The request has succeeded, used for Create operations
204: The request has succeeded and no data is returned, used for Delete operation
4xx: Client error
5xx: Server Error