Los endpoints de API están documentados con la especificación OpenAPI 3.0 utilizada en Swagger.

Puede acceder a la documentación de la última versión de iceScrum aquí: https://www.icescrum.com/api.

Si está utilizando su propio servidor (on-premise), agregue /api a su URL para leer la documentación correspondiente.

Todas las llamadas a la API requieren autenticación. Para hacer esto, el primer paso es generar un token abriendo la pestaña correspondiente en su perfil. Dale un nombre a tu token para reconocerlo.

Los tokens le dan acceso completo a su cuenta a través de la API iceScrum. Para usar un token para autenticar una solicitud, agregue el encabezado HTTP x-icescrum-token.

x-icescrum-token: bezfjoqspo54zefzefe845e58sf

Para compatibilidad con servicios externos, también se pueden usar alias: x-gitlab-token, x-auth-token. Si no controla el encabezado HTTP, puede suministrar el token utilizando el parámetro de solicitud icescrum-token en la URL, sin embargo, esto es menos seguro y debería ser evitado si es posible.

Cuando utiliza un token de autenticación que pertenece a un usuario, obtiene todos los permisos para ese usuario.

Por lo tanto, la ejecución de una acción a través de la API requiere el mismo rol que en la interfaz de usuario (por ejemplo, Dueño del Producto, Administrador…). Esto significa que, según lo que desee hacer, es posible que deba cambiar de usuario o ajustar roles (ver documentación de roles y permisos).

Del mismo modo, como en la interfaz de usuario, ciertas acciones solo estarán disponibles si activa la App correspondiente o si los elementos manejados tienen un estado específico.

La mayoría de los endpoints iceScrum producen JSON, por lo que debe configurar el encabezado HTTP Aceptar en application/json.

Aquí hay un ejemplo de datos JSON devueltos por 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 está enviando datos a iceScrum, también agregue el encabezado Content-Type a application/json y proporcione sus datos JSON como un cuerpo de solicitud HTTP.

Existe una diferencia entre el formato de los datos que recibe y el formato de los datos que envía a iceScrum. Para enviar un objeto, debe encerrar el objeto en un objeto padre con el tipo de elemento en «camel-case» (comenzando con una letra minúscula). Por ejemplo, para una historia, este cuerpo de solicitud se puede enviar:

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

Ciertos campos enumerados, como los tipos de historias, se representan como números. La correspondencia entre los tipos y el número asociado se proporciona en los diagramas Swagger.

Puede encontrar más detalles sobre lo que puede enviar y recibir para cada endpoint en la documentación de Swagger.

Todas las URL comienzan con la URL de su servidor iceScrum seguido de /ws/

http://iceScrumServer/ws/...

Se proporciona una URL de muestra adecuada para su servidor donde crea los tokens en iceScrum.

Las partes variables de las URL descritas en la documentación de Swagger están rodeadas de llaves. Debe reemplazarlos con los valores reales que está manipulando.

Aquí hay ejemplos del uso de la API con la herramienta de línea de comando 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.