Curioseando la API de Trello

Standard

Trello

Trello es una herramienta que nos permite tener organizados infinidad de tipos de proyectos. Esta herramienta implementa el paradigma de Kanban para administrar los proyectos. Los proyectos son representados por “boards”, que a su vez contienen listas (listas de actividades). Estas listas contienen “cards” que corresponden a tareas. Cada tarjeta se supone que progresa de una lista a otra (arrastrando y soltando). De esta forma podemos llevar un control del proceso que se sigue desde que una tarea es una idea por ejemplo, hasta su realización. Se puede asignar usuarios a las tarjetas. Así mismo los usuarios y “boards” pueden ser agrupados en organizaciones.

trelloboard2

En Hunabsys implementamos un framework ágil de desarrollo que seguro tú ya conoces, Scrum Nos apoyamos en Trello para apoyar Scrum, representando con tableros cada uno de los Sprints de un proyecto y con tarjetas cada una de las historias de usuario y tareas.

Aparte de ser gratis, Trello proporciona una API para desarrolladores, en la cual nos apoyamos para automatizar el proceso de carga de tarjetas de los sprints, monitorear las actividades por usuario, comparar horas invertidas contra horas estimadas, ver el “burndown chart” en tiempo real, entre otros fines.

La API de Trello trabaja con servicios RESTful. Si no haz trabajado con ellos te recomiendo  documentarte un poco sobre cómo es que funcionan antes de seguir leyendo.

En esta ocasión les mostraré algunos ejemplos de peticiones y algunos problemas y detalles que salieron en el desarrollo y que la documentación de la API no resuelve claramente.

Pre-Requisitos y orientación

Para poder utilizar la API de Trello necesitas incluir la biblioteca Trello Client después de incluir JQuery.

<script src="https://api.trello.com/1/client.js?key=your_application_key">...

En cualquier momento puedes consultar https://trello.com/docs y de ahí ver una lista de todas las URLs de la API disponibles.

También tienes a la mano un tablero de Trello, donde los desarrolladores de la API de Trello te resuelven tus dudas. Es muy útil. Este es el link al tablero https://trello.com/api

Haciendo uso de la API

Ejemplos básicos y sencillos para comenzar:

Cargar todas las tarjetas a las que está asignado un miembro:

Trello.get("members/me/cards", function(cards) {
    $cards.empty();
    $.each(cards, function(ix, card) {
    $("<a>")
    .attr({href: card.url, target: "trello"})
    .addClass("card")
    .text(card.name)
    .appendTo($cards);
   }); 
 });

Míralo funcionando en JSFiddle: http://jsfiddle.net/nNesx/

GET 

Petición que te trae los boards de la organización hunabsys-tutorial.

De los boards  se trae sólo el nombre, la url y listas de los mismos, que estén abiertos.

De las listas que se trae, sólo considera su nombre y id del board al que pertenece.

En la API de Trello lo encuentras así:

GET /1/organizations/[idOrg or name]/boards/[filter]

var orgBoardsParams = "filter=open&fields=name,url&lists=open&list_fields=idBoard,name"; 

Trello.get("organizations/hunabsys-tutorial/boards?" + orgBoardsParams, function(boards) {
 /* Contenido de la función callback, que se ejecuta cuando la petición al     servidor ha terminado. En este punto ya se puede trabajar con el           resultado de la petición, en este caso boards. */
});

POST

Petición que crea tarjetas en Trello.

La tarjeta se crea con un nombre, una descripción, se posiciona en una lista y se se asignan labels.

En la API de Trello lo encuentras así:

POST /1/cards

Trello.post("cards",
                { name: us[0],
                  desc: "", 
                  idList: idListUS,
                  idLabels: BacklogLoader.labels[BacklogLoader.USER_STORY]                 } ,
           function(s) { 
             /* Función callback. 
             Haz lo que quieras con el resultado de la petición. */
});

PUT

Petición que actualiza la descripción de la tarjeta que corresponde al id especificado.

En la API de Trello lo encuentras así:

PUT /1/cards/[card id or shortlink]/desc

Trello.put("cards/" + id, { desc: usDesc}, function(s) {
    /* Función callback. 
       Haz lo que quieras con el resultado de la petición. */
 });

Los problemas que surgieron y su solución.

La forma de enviar parámetros

En el desarrollo de la aplicación se necesitó actualizar la descripción de una tarjeta en Trello dado el id de la misma.

 

Screen Shot 2015-08-29 at 1.48.14 PM

 

Código que se implementó:

 

Trello.put(“cards/” + id + “?desc=hola”);

Esa manera de solicitar editar la descripción de la tarjeta funcionó bien durante meses, repentinamente dejó de funcionar, la razón fue que  se modificó la API dejándose de utilizar “querystring” en solicitudes PUT.

La manera correcta era la siguiente:

Trello.put(“cards/” + id, { desc: "hola” });

Presta atención muy bien a la forma en que envías los parámetros en los requests, ya que de esto no hay mucha explicación en la API de Trello.

Ambiguedad y funcionalidad no implementada aún en la API

Cada una de las tarjetas que se manejan en Trello tienen asociados campos o atributos a la misma, como por ejemplo:

  • dueDate: Es la fecha que se le asigna como fecha límite a la actividad para ser terminada.
  • dateLastActivity: Fecha en que se registró la última actividad en esa tarjeta.
  • dateLastView:Fecha en que se registró la última vista de la tarjeta.
  • date:Fecha en que se creó la tarjeta.

Se necesitaba listar todas las tarjetas de un tablero de Trello dado un rango de fechas. Si se consulta la documentación de la API puedes ver que se pueden usar filtros de “since” y “before” como parámetros. Lo que no se explica es cuál fecha se toma en cuenta para el filtro. Yo necesitaba que fuera el “dateLastActivity” de la tarjeta.

Esa funcionalidad aún no está implementada en la API de Trello. Los parámetros “Since” y “Before” consideran sólo la fecha de creación de la tarjeta.

La manera en que resolví el problema fue traerme tan pocas tarjetas como pude con la API y después aplicarles el filtro que deseaba desde mi lado del cliente considerando el campo de “dateLastActivity”.

Funcionalidad no implementada aún en la API

Se necesitaba crear una tarjeta vía la API de Trello y que al mismo tiempo, en el momento de su creación se generara un comentario en la tarjeta.

Se esperaba que fuera algo como lo siguiente:

Trello.post("cards",
            { name: task['task'],
              desc: card.shortUrl,
              idMembers: BacklogLoader.userNames[task['resp']],
              idList: BacklogLoader.idListTasks,
              idLabels: BacklogLoader.labels[BacklogLoader.NEW_FEATURE]
            },
            "/actions/comments",
             {
               text: "This is a comment"
             }
);

Por supuesto, éste código no funciona. Se estaba buscando la mejor solución de la manera de hacer las menos peticiones posibles al servidor. Evitar hacer un POST para la creación de la tarjeta y después un PUT adicional para generar el comentario.

Pues no, los desarrolladores de la API de Trello me contestaron que no se podía, que tenía que crear la tarjeta… y después comentar sobre ella. Así se tuvo que desarrollar.

Conclusión

Bueno, hasta aquí mi aporte del día. Trello es una herramienta muy poderosa y única, si implementas su API puedes sacarle aún más provecho y adaptarlo fácilmente a tus necesidades.

Si tienes alguna duda durante tu incursión en el uso de la API no dudes en consultar la documentación oficial, si no encuentras respuesta ahí consulta en stackoverflow, y si de plano no hay información, o encuentras un bug en la API puedes preguntar en inglés en el Tablero de Trello de los desarrolladores:https://trello.com/api .

 

Leave a Reply

Your email address will not be published. Required fields are marked *