Les endpoints d’API sont documentés avec la spécification OpenAPI 3.0 utilisée dans Swagger.

Vous pouvez accéder à la documentation correspondant à la dernière version d’iceScrum ici : https://www.icescrum.com/api.

Si vous utilisez votre propre serveur (on-premise), ajoutez /api à son URL pour lire la documentation correspondante.

Tous les appels d’API nécessitent une authentification. Pour cela, la première étape consiste à générer un token en ouvrant l’onglet correspondant dans votre profil. Donnez un nom à votre token afin de le reconnaître.

Les tokens donnent un accès complet à votre compte via l’API iceScrum. Pour utiliser un token pour authentifier une requête, ajoutez l’en-tête HTTP x-icescrum-token.

x-icescrum-token: bezfjoqspo54zefzefe845e58sf

Pour la compatibilité avec les services externes, des alias peuvent également être utilisés: x-gitlab-token, x-auth-token. Si vous ne contrôlez pas l’en-tête HTTP, vous pouvez fournir le token à l’aide du paramètre de requête icescrum-token dans l’URL, cependant, c’est moins sûr et doit être évité si possible.

Lorsque vous utilisez un token d’authentification qui appartient à un utilisateur, vous obtenez toutes les autorisations de cet utilisateur.

Ainsi, l’exécution d’une action via l’API nécessite le même rôle que dans l’interface utilisateur (par exemple, Product Owner, Administrateur…). Cela signifie que selon ce que vous voulez faire, vous devrez peut-être changer d’utilisateur ou ajuster les rôles (voir la documentation des rôles et permissions).

De même, comme dans l’interface utilisateur, certaines actions ne seront disponibles que si vous activez l’App correspondante ou si les items manipulés ont un état spécifique.

La plupart des endpoints d’iceScrum produisent du JSON, vous devez donc définir l’en-tête HTTP Accept à application/json.

Voici un exemple de données JSON renvoyées par 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": ""
}

Si vous envoyez des données à iceScrum, ajoutez également l’en-tête Content-Type à application/json et fournissez vos données JSON comme corps de requête HTTP.

Il y a une différence entre le format des données que vous recevez et celui des données que vous envoyez à iceScrum. Pour envoyer un objet, vous devez en effet englober l’objet dans un objet parent avec pour clé le type d’élément en « camel-case » (en commençant par une lettre minuscule). Par exemple, pour une story, ce corps de requête peut être envoyé:

{
    "story": {
        "name": "Hello world"
    }
}

Certains champs énumérés tels que les types de story sont représentés sous forme de nombres. La correspondance entre les types et le nombre associé est fournie dans les schémas Swagger.

Vous trouverez plus de détails sur ce que vous pouvez envoyer et recevoir pour chaque endpoint dans la documentation Swagger.

Toutes les URL commencent par l’URL de votre serveur iceScrum suivi de /ws/

http://iceScrumServer/ws/...

Un exemple d’URL adapté à votre serveur est fourni à l’endroit où vous créez les tokens dans iceScrum.

Les parties variables des URL décrites dans la documentation Swagger sont entourées d’accolades. Vous devez les remplacer par les valeurs réelles que vous manipulez.

Voici des exemples d’utilisation de l’API avec l’outil en ligne de commande cURL :

curl -H "Accept: application/json"                         \
     -H "x-icescrum-token: ab4565465e8aa53bfe57a4587"      \
     https://cloud.icescrum.com/ws/project/MYPROJ/story

curl -H "Accept: application/json"                         \
     -H "x-icescrum-token: ab4565465e8aa53bfe57a4587"      \
     -H "Content-Type: application/json"                   \
     -d '{ "story": { "name": "foo" } }'                   \
     https://cloud.icescrum.com/ws/project/MYPROJ/story

curl -H "Accept: application/json"                         \
     -H "x-icescrum-token: ab4565465e8aa53bfe57a4587"      \
     -H "Content-Type: application/json"                   \
     -d '{ "task": { "name": "bar", "parentStory": { "id": 42 }, "color": "#ff1313" } }'    \
     https://cloud.icescrum.com/ws/project/MYPROJ/task

curl -H "Accept: application/json"                         \
     -H "x-icescrum-token: ab4565465e8aa53bfe57a4587"      \
     https://cloud.icescrum.com/ws/project/MYPROJ/task/story/42

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.