Jira, la versátil plataforma de Atlassian para el seguimiento de incidencias y la gestión de proyectos, se ha convertido en una herramienta indispensable para innumerables equipos de desarrollo de todo el mundo. Aunque su interfaz fácil de usar simplifica la gestión de proyectos y el seguimiento de incidencias, el verdadero poder de Jira reside en sus amplias opciones de personalización y capacidades de integración. En el centro de todo ello se encuentra la API REST de Jira, que abre un mundo de posibilidades para automatizar tareas, crear aplicaciones personalizadas e integrar Jira sin problemas con otras herramientas de su ecosistema de desarrollo. En esta guía completa, profundizaremos en la API REST de Jira, exploraremos sus capacidades y repasaremos ejemplos prácticos para ayudarle a comenzar.
Conclusiones clave: La API REST de Jira es una herramienta versátil para automatizar tareas, crear aplicaciones personalizadas e integrar Jira con otras herramientas de desarrollo tanto en las versiones Cloud como Server/Data Center. Ofrece una amplia variedad de capacidades, incluida la gestión de incidencias, operaciones masivas e informes personalizados, con compatibilidad para funciones avanzadas como la paginación y la expansión de datos. Aunque existen algunas diferencias entre las versiones, la funcionalidad principal de la API se mantiene coherente, lo que permite a los equipos personalizar Jira de manera eficiente según sus necesidades específicas e integrarlo sin problemas con su ecosistema de desarrollo.
Puede probar Jira sin usar la API en Latenode
¿Qué es la API de Jira?
En esencia, una API (Application Programming Interface o interfaz de programación de aplicaciones) es un conjunto de protocolos y herramientas que especifican cómo deben interactuar los componentes de software. En el contexto de Jira, la API permite que las aplicaciones externas interactúen con Jira de forma programática, posibilitando la recuperación y manipulación de datos, así como la ejecución de acciones dentro de Jira. Jira proporciona dos tipos de API:
¿Qué es la API de Java?
La API Java de Jira es una potente herramienta para desarrolladores que crean aplicaciones o plugins personalizados para Jira. Proporciona acceso directo a los objetos y métodos Java subyacentes del servidor de Jira, lo que permite una integración y personalización profundas. Sin embargo, este nivel de acceso solo está disponible para instalaciones locales de Jira (Server o Data Center), donde tiene acceso directo al servidor. Si trabaja con Jira Cloud o crea una integración independiente, la API REST es la mejor opción.
¿Qué es la API REST?
REST (Representational State Transfer) es un estilo arquitectónico que define un conjunto de restricciones para crear servicios web. Una API REST expone un conjunto de endpoints HTTP a los que se puede acceder enviando solicitudes con métodos HTTP específicos (GET, POST, PUT, DELETE) para realizar operaciones sobre recursos.
La API REST de Jira sigue esta arquitectura y proporciona un conjunto completo de endpoints para interactuar con casi todos los aspectos de Jira, desde incidencias y proyectos hasta tableros ágiles y paneles. Devuelve datos en formato JSON y admite diversos métodos de autenticación para garantizar un acceso seguro.
Una de las principales ventajas de la API REST es su independencia de plataforma: puede llamar a la API desde cualquier dispositivo o aplicación que pueda realizar solicitudes HTTP, independientemente del lenguaje de programación utilizado. Esto la convierte en la opción ideal para crear integraciones entre Jira y otras herramientas, o para crear scripts de interacción con Jira desde la línea de comandos.
¿Qué puede hacer con la API REST de Jira?
Las posibilidades son casi infinitas. Estos son solo algunos ejemplos de lo que puede lograr con la API REST de Jira:
- Automatizar la creación de incidencias: Integre Jira con su sistema de seguimiento de errores o herramienta de soporte al cliente para crear automáticamente incidencias en Jira cuando ocurran determinados eventos, con todos los detalles relevantes.
- Sincronizar datos entre sistemas: Mantenga Jira sincronizado con otras herramientas de su canalización de desarrollo, como sistemas de control de código fuente, herramientas de CI/CD o suites de gestión de pruebas. La API le permite reflejar cambios de Jira en otros sistemas y viceversa.
- Operaciones masivas: ¿Necesita actualizar una gran cantidad de incidencias a la vez? La API REST admite operaciones masivas de creación, actualización y eliminación, lo que le ahorra incontables horas de trabajo manual.
- Paneles e informes personalizados: Recupere datos de Jira y utilícelos para crear paneles, informes o visualizaciones de datos personalizados adaptados a las necesidades específicas de su equipo.
- Ampliar la funcionalidad de Jira: Cree aplicaciones e integraciones personalizadas que amplíen las capacidades de Jira, añadan nuevas funciones o simplifiquen flujos específicos de su organización.
- Migrar datos: ¿Está migrando desde otro sistema de seguimiento de incidencias a Jira? Utilice la API para importar programáticamente sus datos existentes a Jira.
- Realizar copias de seguridad y archivar: Configure scripts para hacer copias de seguridad periódicas de sus datos de Jira o archivar proyectos e incidencias antiguos.
Estos son solo algunos ejemplos: la API REST de Jira proporciona un amplio conjunto de endpoints que cubren casi todas las funciones y características disponibles en la interfaz de usuario de Jira. Si puede hacerlo en Jira, es muy probable que pueda hacerlo mediante la API.
Diferencias clave entre la API REST de Jira Cloud y la API REST de Data Center
Aunque la API REST de Jira proporciona en gran medida las mismas capacidades en Jira Cloud, Server y Data Center, hay algunas diferencias clave que debe tener en cuenta:
- Autenticación: Jira Cloud utiliza OAuth 2.0 o tokens de API para la autenticación, proporcionando un método seguro y basado en estándares para conceder acceso a la API. Jira Data Center, por otro lado, utiliza principalmente autenticación básica o cookies de sesión.
- Versionado de la API: La API REST de Jira Cloud está versionada (actualmente en la versión 3), lo que permite a Atlassian evolucionar y mejorar la API con el tiempo sin romper las integraciones existentes. Jira Data Center, sin embargo, no cuenta con un versionado explícito: la API está vinculada a la versión específica de Jira.
- Limitación de solicitudes: Para garantizar un uso justo y mantener el rendimiento, Jira Cloud aplica límites de solicitudes a la API más estrictos que Data Center. Las integraciones deben diseñarse teniendo en cuenta estos límites e implementar una limitación y gestión de errores adecuadas.
- Formato de URL: Las URL de los endpoints de la API REST difieren ligeramente entre Cloud y Data Center. Para Jira Cloud, la URL base tiene el formato https://your-domain.atlassian.net/rest/api/3/, mientras que para Data Center es https://your-jira-instance.com/rest/api/latest/.
A pesar de estas diferencias, los conceptos básicos y patrones de uso de la API REST siguen siendo en gran medida los mismos en todas las implementaciones. Las habilidades y conocimientos que obtenga trabajando con una versión de la API serán fácilmente transferibles a las demás.
¿Qué necesita para trabajar con la API REST de Jira?
Para comenzar con la API REST de Jira, necesitará:
- Una instancia de Jira: Puede ser un sitio de Jira Cloud o una instancia autohospedada de Jira Server o Data Center. Necesitará acceso de administrador para configurar y gestionar sus integraciones de API.
- Credenciales de autenticación: Dependiendo de su implementación de Jira, puede tratarse de un token OAuth 2.0, un token de API o credenciales de autenticación básica (nombre de usuario y contraseña).
- Cliente de API: Para realizar solicitudes HTTP a la API, necesitará un cliente de API. Puede ser una herramienta especializada de pruebas de API como Postman, una herramienta de línea de comandos como cURL o la biblioteca HTTP del lenguaje de programación que prefiera (por ejemplo, la biblioteca requests de Python o la API fetch de JavaScript).
- Referencia de la documentación de la API de Jira: Atlassian proporciona documentación extensa sobre la API REST de Jira, con detalles de cada endpoint, sus parámetros y ejemplos de solicitudes y respuestas. Manténgala a mano mientras explora la API.
Con estos elementos listos, puede empezar a realizar sus primeras solicitudes a la API.
Cómo usar la API REST de Jira
Veamos un ejemplo práctico de uso de la API REST de Jira para crear, recuperar, actualizar y buscar incidencias. Usaremos Postman en nuestros ejemplos, pero los principios se aplican a cualquier cliente de API.
Paso 1: Crear una cuenta de Jira Cloud
Si todavía no tiene una instancia de Jira con la que trabajar, la forma más sencilla de comenzar es registrarse para obtener una instancia gratuita de Jira Cloud en https://www.atlassian.com/software/jira. Una vez configurado su sitio, cree un nuevo proyecto con el que trabajar.
Paso 2: Generar un token de API de Jira
Para autenticar nuestras solicitudes de API, utilizaremos un token de API. Así puede generar uno:
- Inicie sesión en su cuenta de Atlassian y vaya a https://id.atlassian.com/manage-profile/security/api-tokens.
- Haga clic en "Create API token", asigne a su token una etiqueta descriptiva y haga clic en "Create".
- Copie el token generado y guárdelo de forma segura. No podrá volver a verlo después de salir de esta página.
Paso 3: Realizar su primera solicitud de API con Postman
Comencemos recuperando los detalles de una incidencia existente:
- Abra Postman y cree una nueva solicitud.
- Establezca el método HTTP en GET e introduzca la URL del endpoint de detalles de incidencias, sustituyendo your-domain por el dominio de su sitio de Jira e ISSUE-KEY por la clave de una incidencia de su proyecto: https://your-domain.atlassian.net/rest/api/3/issue/ISSUE-KEY
- En la pestaña "Authorization", seleccione "Basic Auth" como tipo. Introduzca la dirección de correo electrónico de su cuenta de Atlassian como nombre de usuario y pegue su token de API como contraseña.
- Haga clic en "Send". Si todo está configurado correctamente, debería ver una respuesta JSON con todos los detalles de la incidencia especificada, incluidos sus campos, comentarios, adjuntos y más.
Paso 4: Crear una incidencia
Ahora creemos una nueva incidencia mediante la API:
- En Postman, cambie el método HTTP a POST y actualice la URL al endpoint de creación de incidencias: https://your-domain.atlassian.net/rest/api/3/issue
- En la pestaña "Headers", añada un nuevo par clave-valor: "Content-Type" y "application/json". Esto indica a Jira que estamos enviando una carga útil JSON.
Cambie a la pestaña "Body", seleccione el botón de opción "raw" e introduzca el siguiente JSON, sustituyendo según corresponda los valores de project.key, issuetype.name, summary y description:
json
{
"fields": {
"project": {
"key": "YOUR_PROJECT_KEY"
},
"issuetype": {
"name": "Task"
},
"summary": "Issue created via REST API",
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "This is a test issue created using the Jira REST API."
}
]
}
]
}
}
}
3. Haga clic en "Send". Jira responderá con un estado 201 Created y todos los detalles de la incidencia recién creada.
Paso 5: Actualizar una incidencia
Para actualizar una incidencia existente, utilizamos el método PUT:
- Cambie el método HTTP a PUT y actualice la URL para que apunte a la incidencia que desea actualizar: https://your-domain.atlassian.net/rest/api/3/issue/ISSUE-KEY
En el cuerpo de la solicitud, incluya los campos que desea actualizar, por ejemplo:
json
{
"fields": {
"summary": "Updated summary",
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "This issue has been updated via the REST API."
}
]
}
]
}
}
}
2. Haga clic en "Send". Jira responderá con un estado 204 No Content para indicar que la actualización se realizó correctamente.
Paso 6: Buscar incidencias mediante JQL
Las potentes capacidades de búsqueda de Jira también son accesibles mediante la API REST utilizando JQL (Jira Query Language):
- Vuelva a cambiar el método HTTP a POST y actualice la URL al endpoint de búsqueda: https://your-domain.atlassian.net/rest/api/3/search
En el cuerpo de la solicitud, incluya una consulta JQL y cualquier parámetro adicional:
json
Copy
{
"jql": "project = YOUR_PROJECT_KEY AND status = 'To Do' ORDER BY created DESC",
"fields": ["summary", "status", "assignee"],
"maxResults": 10
}
Esta consulta devolverá las 10 incidencias creadas más recientemente con el estado 'To Do' del proyecto especificado, incluyendo únicamente los campos de resumen, estado y responsable.
- Haga clic en "Send". Jira responderá con un array JSON de incidencias que coincidan con sus criterios de búsqueda.
Estos ejemplos solo muestran una pequeña parte de lo que es posible con la API REST de Jira. A medida que se familiarice con los endpoints y parámetros disponibles, podrá crear integraciones cada vez más complejas y potentes.
Puede automatizar Jira sin usar la API en Latenode
Cómo automatizar la creación y actualización de incidencias en Jira con Latenode
Una de las aplicaciones más potentes de la API REST de Jira es la automatización de la creación y actualización de tareas. Con Latenode, puede configurar flujos sofisticados que crean y actualizan automáticamente tareas en Jira basándose en datos de fuentes externas o activadores específicos. Esto garantiza que la información de su sistema de gestión de proyectos permanezca actualizada y llegue a tiempo, mejorando la eficiencia del equipo.
Por ejemplo, puede crear un flujo que genere automáticamente una nueva tarea en Jira cuando se reciba un mensaje de error de un sistema de monitorización, completando todos los campos necesarios y asignando la tarea al desarrollador correspondiente. A medida que lleguen actualizaciones, la tarea se puede actualizar automáticamente y, cuando se resuelva la incidencia, se puede cerrar. Este enfoque optimizado no solo mejora el seguimiento de incidencias, sino que también ahorra tiempo a su equipo, permitiéndole centrarse en resolver problemas en lugar de administrarlos.
Puede obtener más información sobre este script y la integración con Latenode en este artículo. La integración con Latenode ofrece algunos beneficios clave:
- Facilidad de uso: Latenode simplifica el proceso de utilizar la API de Jira, facilitando a los usuarios no técnicos la automatización de tareas de gestión de proyectos.
- Precios flexibles: Los usuarios pueden elegir entre distintos planes de Latenode, con diferentes costes y funciones, para adaptarse mejor a sus necesidades.
- Soluciones integrales: La integración de Latenode con Jira proporciona acceso a una amplia gama de capacidades de gestión de proyectos y seguimiento de incidencias.
- Personalización: Los usuarios pueden adaptar las integraciones de Jira a sus necesidades específicas, lo que permite soluciones de automatización personalizadas y alineadas con los objetivos empresariales.
Imagine que cada correo electrónico importante de un cliente se transforma automáticamente en una tarea en Jira. Con Latenode, esto se hace realidad. Nuestra plataforma garantiza la creación de una nueva tarea en el proyecto correcto con campos completados según el contenido del correo electrónico, asegurando que no se pierda ninguna solicitud importante.
A continuación se muestra un ejemplo de cómo un flujo de Latenode automatiza la creación y actualización de tareas de Jira basándose en datos de correos electrónicos entrantes de una fuente externa.
Esta imagen mostraría una representación visual del flujo en la interfaz de Latenode, con nodos conectados que representan cada paso del proceso, desde la recepción del correo electrónico hasta la creación de la tarea en Jira.
Este es solo un ejemplo de cómo Latenode puede transformar su enfoque para utilizar la API de Jira con una automatización potente. De hecho, las capacidades de la plataforma son prácticamente ilimitadas: puede crear cualquier flujo de automatización necesario para mejorar la eficiencia de su empresa. Ya sea distribución automática de tareas, envío de notificaciones, seguimiento de indicadores clave de rendimiento o cualquier otra tarea, Latenode proporciona las herramientas para hacerlas realidad.
Al aprovechar el creador visual de flujos de Latenode y la integración fluida con la API REST de Jira, puede diseñar e implementar fácilmente flujos de automatización complejos, aumentar la eficiencia de la gestión de proyectos y acelerar los flujos de trabajo de su equipo.
Si necesita ayuda o asesoramiento sobre cómo crear su propio script, o si desea replicar este, contacte con nuestra comunidad de Discord, donde se encuentran los expertos en automatización low-code.
Paginación, expansión y ordenación en la API REST de Jira
A medida que empiece a trabajar con conjuntos de datos más grandes en Jira, deberá conocer cómo gestiona la API REST la paginación, la expansión de recursos anidados y la ordenación de resultados.
Expansión
Muchos recursos de Jira contienen referencias a otros recursos anidados. Por ejemplo, una incidencia contiene referencias a su proyecto, tipo de incidencia, creador, informador, responsable, comentarios, adjuntos y más. De forma predeterminada, estos recursos anidados se devuelven como resúmenes, que contienen solo algunos campos básicos y un enlace propio al recurso completo.
Si necesita todos los detalles de un recurso anidado, puede utilizar el parámetro de consulta expand para solicitar que Jira incluya el recurso completo en la respuesta. Por ejemplo, para incluir todos los detalles del proyecto y del responsable de una incidencia:
GET .../rest/api/3/issue/ISSUE-KEY?expand=project,assignee
Puede expandir varios recursos separándolos con comas. Tenga en cuenta que las expansiones pueden aumentar considerablemente el tamaño de la carga útil de respuesta, así que utilícelas con criterio.
Paginación
Las solicitudes que podrían devolver una gran cantidad de resultados (como las búsquedas JQL) se paginan de forma predeterminada. La API devolverá un número máximo de resultados por página (50 de forma predeterminada, aunque se puede personalizar hasta 100) junto con enlaces a las páginas siguiente y anterior.
Puede controlar la paginación mediante los parámetros startAt y maxResults:
- startAt: El índice del primer resultado que se devolverá (con base 0)
- maxResults: El número máximo de resultados que se devolverán por página
Por ejemplo, para recuperar la segunda página de resultados con un tamaño de página de 20:
GET .../rest/api/3/search?jql=project=YOUR_PROJECT_KEY&startAt=20&maxResults=20
Su aplicación deberá gestionar múltiples solicitudes para recuperar todas las páginas de resultados.
Ordenación
Puede controlar el orden de los resultados mediante el parámetro orderBy, que acepta una lista de campos separados por comas para ordenar. Cada campo puede llevar el prefijo - para indicar orden descendente.
Por ejemplo, para ordenar incidencias por fecha de creación en orden descendente y, después, por prioridad en orden ascendente:
GET .../rest/api/3/search?jql=project=YOUR_PROJECT_KEY&orderBy=-created,priority
No todos los campos admiten ordenación; consulte la documentación del endpoint específico para ver qué opciones están disponibles.
Ejemplos de uso de la API de Jira
A continuación se presentan algunos ejemplos más avanzados que demuestran la potencia de la API REST de Jira para operaciones masivas.
Creación/actualización masiva de incidencias desde CSV
Suponga que tiene un archivo CSV con datos de varias incidencias que desea crear o actualizar en Jira. Puede utilizar una herramienta como Postman para automatizar este proceso:
- En Postman, cree una nueva solicitud para el endpoint de creación o actualización de incidencias.
En la pestaña Body, seleccione el botón de opción "raw" e introduzca una plantilla para los datos de su incidencia, utilizando variables para los campos que provendrán de su CSV:
{
"fields": {
"project": {"key": "{{project_key}}"},
"issuetype": {"name": "{{issue_type}}"},
"summary": "{{summary}}",
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "{{description}}"
}
]
}
]
},
"assignee": {"name": "{{assignee}}"},
"priority": {"name": "{{priority}}"}
}
}
2. Cambie a la pestaña "Pre-request Script" y añada código para leer su archivo CSV y establecer las variables correspondientes:
const csvFile = pm.iterationData.readCSV();
pm.variables.set('project_key', csvFile[0]);
pm.variables.set('issue_type', csvFile[1]);
pm.variables.set('summary', csvFile[2]);
pm.variables.set('description', csvFile[3]);
pm.variables.set('assignee', csvFile[4]);
pm.variables.set('priority', csvFile[5]);
3. En la ventana "Runner", seleccione su archivo CSV como archivo de datos e inicie la ejecución. Postman creará una nueva solicitud para cada fila de su CSV, sustituyendo las variables con los valores del archivo.
Esta es una técnica potente para importar datos de forma masiva a Jira desde fuentes externas.
Creación/actualización masiva de incidencias desde JSON
Si sus datos de origen ya están en formato JSON, puede utilizar el endpoint de creación/actualización masiva para procesar varias incidencias en una sola solicitud:
POST https://your-domain.atlassian.net/rest/api/3/issue/bulk
El cuerpo de la solicitud debe contener un array de objetos de creación/actualización de incidencias, cada uno siguiendo el mismo formato que una solicitud individual de creación/actualización de incidencias:
{
"issueUpdates": [
{
"fields": {
"project": {"key": "PROJ1"},
"issuetype": {"name": "Task"},
"summary": "Issue 1",
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "First issue created via bulk update"
}
]
}
]
}
}
},
{
"fields": {
"project": {"key": "PROJ2"},
"issuetype": {"name": "Bug"},
"summary": "Issue 2",
"description": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"type": "text",
"text": "Second issue created via bulk update"
}
]
}
]
},
"priority": {"name": "High"},
"labels": ["bulk-import", "api-test"]
}
}
]
}
Esto creará dos incidencias en una solicitud: una Task en el proyecto PROJ1 y un Bug en el proyecto PROJ2. Puede incluir hasta 50 incidencias en una sola solicitud masiva.
El endpoint masivo también es útil para realizar transiciones, actualizaciones y eliminaciones masivas. Por ejemplo, para mover varias incidencias al estado "Done":
{
"transition": {
"id": "31"
},
"issues": [
{"key": "ISSUE-1"},
{"key": "ISSUE-2"},
{"key": "ISSUE-3"}
]
}
Esto supone que "31" es el ID de su transición "Done"; puede encontrar las transiciones disponibles para un tipo de incidencia mediante el endpoint /rest/api/3/issue/{issueIdOrKey}/transitions.
Resumen
La API REST de Jira es una herramienta extremadamente potente para integrar Jira con otros sistemas, automatizar tareas y ampliar las capacidades de Jira. En esta guía, hemos cubierto los fundamentos de la API, incluidos:
- La diferencia entre las API Java y REST, y cuándo utilizar cada una
- Las diferencias clave entre las API de Cloud y Server/Data Center
- Cómo autenticarse en la API mediante tokens de API o Basic Auth
- Cómo realizar sus primeras solicitudes de API con Postman
- Crear, recuperar, actualizar y buscar incidencias
- Gestionar la paginación, expansión y ordenación de resultados
- Casos de uso avanzados como la creación/actualización masiva a partir de datos CSV y JSON
Sin embargo, apenas hemos arañado la superficie. La API REST de Jira proporciona endpoints para trabajar con casi todos los aspectos de Jira, desde proyectos y tableros hasta usuarios y permisos. A medida que cree sus integraciones, asegúrese de consultar la documentación oficial de Atlassian para obtener la información más actualizada y completa.
Con la API REST de Jira en su conjunto de herramientas, las posibilidades de lo que puede hacer con Jira son casi infinitas. Ya sea que esté creando un panel de informes personalizado, sincronizando datos con otro sistema o automatizando flujos complejos, la API proporciona la flexibilidad y potencia que necesita para hacerlo realidad.
Puede probar Jira sin usar la API en Latenode
