Visual Studio Online APIs

Durante el TechEd 2014 se presentó una nueva API para acceder a Visual Studio Online. Esta nos permite integrar servicios de terceros en Visual Studio Online, como Trello, Github, Jenkins, etc. Además, gracias a ella, podemos crearnos nuestras propias aplicaciones para extender las funcionalidades de Visual Studio Online, proporcionando una solución de ALM completa y totalmente personalizada en la nube.

Esta API se basa en tecnologías web estandarizadas REST, JSON y OAUTH2, y nos permite acceder y modificar los datos de los diferentes servicios de Visual Studio Online, como por ejemplo los proyectos, las cuentas, las tareas, etc.

Por ejemplo, para obtener los diferentes proyectos que tenemos en nuestra cuenta de Visual Studio Online, lo podríamos realizar de la siguiente manera:

GET https://{cuenta}.visualstudio.com/defaultcollection/_apis/projects?api-version=1.0-preview

Esto nos devolvería un JSON con el siguiente formato:

  1: Status Code 200
  2: {
  3:     "count": 1,
  4:     "value": [
  5:         {
  6:             "id": "12f16acc-119b-40e5-b623-42511111e40d",
  7:             "name": "Ejemplo",
  8:             "url": "https://{cuenta}.visualstudio.com/DefaultCollection/_apis/projects/12f16acc-119b-40e5-b623-42511111e40d",
  9:             "collection": {
  10:                 "id": "58517134-1111-4430-9f49-c092aecae734",
  11:                 "name": "DefaultCollection",
  12:                 "url": "https://{cuenta}.visualstudio.com/_apis/projectCollections/58517134-1111-4430-9f49-c092aecae734",
  13:                 "collectionUrl": "https://{cuenta}.visualstudio.com/DefaultCollection"
  14:             },
  15:             "defaultTeam": {
  16:                 "id": "395a3875-1111-484f-ac74-57370f4aae53",
  17:                 "name": "GusenetDemo Team",
  18:                 "url": "https:// {cuenta}.visualstudio.com/DefaultCollection/_apis/projects/12f16acc-1111-40e5-b623-42527280e40d/teams/395a3875-034b-484f-ac74-57370f4aae53"
  19:             }
  20:         }
  21:     ]
  22: }

La API está versionada para evitar que las diferentes aplicaciones de los clientes dejen de funcionar debido a posibles actualizaciones. Por este motivo en cada petición hay que indicar la versión que se está utilizando mediante el parámetro api-version. Actualmente la API está en Preview, y la versión que tenemos que especificar es la 1.0-preview.

Tenemos a nuestra disposición una documentación completa de todos los recursos a los que podemos acceder, junto con ejemplos de uso.

Como se trata de una API REST, para comunicarnos con ella hay que usar los diferentes verbos HTTP:

Los códigos de respuesta HTTP nos indican si la operación ha tenido éxito o no. Estos son los diferentes códigos de respuesta que nos puede devolver:

Lo último que nos queda para poder realizar peticiones a la API es la autenticación. Para esto se puede utilizar autenticación básica activando las credenciales alternativas, aunque esta función está más orientada a facilitar el desarrollo de nuestra aplicación. Lo habitual es utilizar OAuth2, y de esta manera no hacemos al usuario tener diferentes cuentas.

Visual Studio Online implementa OAuth de manera estándar, por lo que hay que seguir los mismos pasos que seguiríamos en otros servicios:

• Registrar nuestra aplicación en Visual Studio Online
• Autorizar al usuario de nuestra aplicación
• Obtener el token de autorización
• Usar el token en cada petición.

Podemos encontrar más información sobre cómo realizar todo el proceso OAuth con Visual Studio Online aquí: Authorize access with OAuth 2.0

Además de la API REST, Visual Studio Online también expone una colección de servicios Hookque nos permiten suscribir nuestra aplicación a determinados eventos y así no tener que estar haciendo polling constantemente para comprobar si hay datos nuevos. Por ahora estos son los eventos a los que nos podemos suscribir:

• Cuando finaliza una compilación.
• Cuando se realiza un Push (Git).
• Cuando se realiza un checked in (TFVC).
• Cuando se crea una tarea.
• Cuando se actualiza una tarea.

Junto con esta nueva API se ha creado un nuevo portal de integración con Visual Studio. En este portal podemos encontrar información detallada sobre integración con Visual Studio IDE, Team Foundation Server y Visual Studio Online.

Un saludo.

Carlos Carrillo Boj (3lcarry)