Jira, a versátil plataforma de rastreamento de issues e gerenciamento de projetos da Atlassian, tornou-se uma ferramenta indispensável para inúmeras equipes de desenvolvimento em todo o mundo. Embora sua interface intuitiva facilite o gerenciamento de projetos e o acompanhamento de issues, o verdadeiro poder do Jira está em suas amplas opções de personalização e recursos de integração. O elemento central disso é a API REST do Jira, que abre um mundo de possibilidades para automatizar tarefas, criar aplicativos personalizados e integrar o Jira perfeitamente a outras ferramentas do seu ecossistema de desenvolvimento. Neste guia completo, vamos explorar em profundidade a API REST do Jira, seus recursos e exemplos práticos para ajudar você a começar.
Principais conclusões: A API REST do Jira é uma ferramenta versátil para automatizar tarefas, criar aplicativos personalizados e integrar o Jira com outras ferramentas de desenvolvimento nas versões Cloud e Server/Data Center. Ela oferece uma ampla variedade de recursos, incluindo gerenciamento de issues, operações em massa e relatórios personalizados, com suporte a recursos avançados como paginação e expansão de dados. Embora existam algumas diferenças entre as versões, a funcionalidade central da API permanece consistente, permitindo que as equipes personalizem o Jira de forma eficiente para suas necessidades específicas e o integrem perfeitamente ao ecossistema de desenvolvimento.
Você pode experimentar o Jira sem usar API no Latenode
O que é a API do Jira?
Em sua essência, uma API (Application Programming Interface, ou Interface de Programação de Aplicações) é um conjunto de protocolos e ferramentas que especificam como os componentes de software devem interagir. No contexto do Jira, a API permite que aplicativos externos interajam com o Jira de forma programática, possibilitando a recuperação e manipulação de dados, além da execução de ações dentro do Jira. O Jira oferece dois tipos de APIs:
O que é a API Java
A API Java do Jira é uma ferramenta poderosa para desenvolvedores que criam aplicativos ou plugins personalizados para o Jira. Ela fornece acesso direto aos objetos e métodos Java subjacentes do servidor Jira, permitindo integração e personalização profundas. No entanto, esse nível de acesso está disponível apenas para instalações locais do Jira (Server ou Data Center), nas quais você tem acesso direto ao servidor. Se estiver trabalhando com Jira Cloud ou criando uma integração independente, a API REST é a melhor opção.
O que é uma API REST
REST (Representational State Transfer) é um estilo arquitetural que define um conjunto de restrições para criar serviços web. Uma API REST expõe um conjunto de endpoints HTTP que podem ser acessados enviando solicitações com métodos HTTP específicos (GET, POST, PUT, DELETE) para executar operações em recursos.
A API REST do Jira segue essa arquitetura e fornece um conjunto abrangente de endpoints para interagir com praticamente todos os aspectos do Jira, desde issues e projetos até quadros ágeis e dashboards. Ela retorna dados no formato JSON e oferece suporte a diversos métodos de autenticação para garantir um acesso seguro.
Uma das principais vantagens da API REST é sua independência de plataforma: você pode chamar a API a partir de qualquer dispositivo ou aplicativo capaz de fazer solicitações HTTP, independentemente da linguagem de programação utilizada. Isso a torna a escolha ideal para criar integrações entre o Jira e outras ferramentas ou automatizar interações com o Jira pela linha de comando.
O que você pode fazer com a API REST do Jira?
As possibilidades são quase infinitas. Veja apenas alguns exemplos do que você pode alcançar com a API REST do Jira:
- Automatizar a criação de issues: Integre o Jira ao seu sistema de rastreamento de erros ou ferramenta de suporte ao cliente para criar automaticamente issues no Jira quando determinados eventos ocorrerem, com todos os detalhes relevantes.
- Sincronizar dados entre sistemas: Mantenha o Jira sincronizado com outras ferramentas do seu pipeline de desenvolvimento, como sistemas de controle de código-fonte, ferramentas de CI/CD ou suítes de gerenciamento de testes. A API permite refletir alterações do Jira em outros sistemas e vice-versa.
- Operações em massa: Precisa atualizar um grande número de issues de uma vez? A API REST oferece suporte a operações em massa de criação, atualização e exclusão, economizando inúmeras horas de trabalho manual.
- Dashboards e relatórios personalizados: Recupere dados do Jira e use-os para criar dashboards, relatórios ou visualizações de dados personalizados de acordo com as necessidades específicas da sua equipe.
- Expandir as funcionalidades do Jira: Crie aplicativos e integrações personalizados que ampliem os recursos do Jira, adicionem novos recursos ou simplifiquem fluxos específicos da sua organização.
- Migrar dados: Está migrando de outro sistema de rastreamento de issues para o Jira? Use a API para importar programaticamente seus dados existentes para o Jira.
- Backup e arquivamento: Configure scripts para fazer backup regular dos seus dados do Jira ou arquivar projetos e issues antigos.
Esses são apenas alguns exemplos: a API REST do Jira fornece um amplo conjunto de endpoints que abrange praticamente todos os recursos e funções disponíveis na interface de usuário do Jira. Se você consegue fazer algo no Jira, provavelmente também consegue fazer pela API.
Principais diferenças entre a API REST do Jira Cloud e a API REST do Data Center
Embora a API REST do Jira ofereça praticamente os mesmos recursos no Jira Cloud, Server e Data Center, há algumas diferenças importantes das quais você deve estar ciente:
- Autenticação: O Jira Cloud usa OAuth 2.0 ou tokens de API para autenticação, oferecendo um método seguro e baseado em padrões para conceder acesso à API. Já o Jira Data Center usa principalmente autenticação básica ou cookies de sessão.
- Versionamento da API: A API REST do Jira Cloud possui versionamento (atualmente na versão 3), permitindo que a Atlassian evolua e melhore a API ao longo do tempo sem interromper as integrações existentes. O Jira Data Center, por outro lado, não possui versionamento explícito: a API está vinculada à versão específica do Jira.
- Limitação de taxa: Para garantir uso justo e manter o desempenho, o Jira Cloud aplica limites de taxa mais rígidos às solicitações da API em comparação ao Data Center. As integrações precisam ser projetadas levando esses limites em conta e implementar controle de solicitações e tratamento de erros adequados.
- Formato de URL: As URLs dos endpoints da API REST diferem ligeiramente entre Cloud e Data Center. Para o Jira Cloud, a URL base está no formato https://your-domain.atlassian.net/rest/api/3/, enquanto para o Data Center é https://your-jira-instance.com/rest/api/latest/.
Apesar dessas diferenças, os conceitos principais e os padrões de uso da API REST permanecem praticamente os mesmos entre as implantações. As habilidades e o conhecimento adquiridos trabalhando com uma versão da API serão facilmente transferíveis para as demais.
O que você precisa para trabalhar com a API REST do Jira?
Para começar a usar a API REST do Jira, você precisará de:
- Uma instância do Jira: Pode ser um site do Jira Cloud ou uma instância autogerenciada do Jira Server ou Data Center. Você precisará de acesso administrativo para configurar e gerenciar suas integrações de API.
- Credenciais de autenticação: Dependendo da sua implantação do Jira, pode ser um token OAuth 2.0, um token de API ou credenciais de autenticação básica (nome de usuário e senha).
- Cliente de API: Para fazer solicitações HTTP à API, você precisará de um cliente de API. Pode ser uma ferramenta dedicada de testes de API como Postman, uma ferramenta de linha de comando como cURL ou a biblioteca HTTP da linguagem de programação que escolher (por exemplo, a biblioteca requests do Python ou a API fetch do JavaScript).
- Referência da documentação da API do Jira: A Atlassian fornece ampla documentação para a API REST do Jira, detalhando cada endpoint, seus parâmetros e exemplos de solicitações e respostas. Mantenha-a à mão enquanto explora a API.
Com esses elementos prontos, você poderá começar a fazer suas primeiras solicitações de API.
Como usar a API REST do Jira
Vamos analisar um exemplo prático de uso da API REST do Jira para criar, recuperar, atualizar e pesquisar issues. Usaremos o Postman nos exemplos, mas os princípios se aplicam a qualquer cliente de API.
Etapa 1: Crie uma conta do Jira Cloud
Caso ainda não tenha uma instância do Jira para utilizar, a maneira mais simples de começar é criar uma instância gratuita do Jira Cloud em https://www.atlassian.com/software/jira. Depois que seu site estiver configurado, crie um novo projeto para trabalhar.
Etapa 2: Gere um token de API do Jira
Para autenticar nossas solicitações de API, usaremos um token de API. Veja como gerar um:
- Faça login na sua conta Atlassian e acesse https://id.atlassian.com/manage-profile/security/api-tokens.
- Clique em "Create API token", dê ao token um rótulo descritivo e clique em "Create".
- Copie o token gerado e armazene-o com segurança. Você não poderá visualizá-lo novamente depois de sair desta página.
Etapa 3: Faça sua primeira solicitação de API com o Postman
Vamos começar recuperando os detalhes de uma issue existente:
- Abra o Postman e crie uma nova solicitação.
- Defina o método HTTP como GET e insira a URL do endpoint de detalhes da issue, substituindo your-domain pelo domínio do seu site Jira e ISSUE-KEY pela chave de uma issue no seu projeto: https://your-domain.atlassian.net/rest/api/3/issue/ISSUE-KEY
- Na guia "Authorization", selecione "Basic Auth" como tipo. Insira o endereço de e-mail da sua conta Atlassian como nome de usuário e cole seu token de API como senha.
- Clique em "Send". Se tudo estiver configurado corretamente, você verá uma resposta JSON com todos os detalhes da issue especificada, incluindo campos, comentários, anexos e muito mais.
Etapa 4: Crie uma issue
Agora, vamos criar uma nova issue pela API:
- No Postman, altere o método HTTP para POST e atualize a URL para o endpoint de criação de issues: https://your-domain.atlassian.net/rest/api/3/issue
- Na guia "Headers", adicione um novo par chave-valor: "Content-Type" e "application/json". Isso informa ao Jira que estamos enviando uma carga JSON.
Mude para a guia "Body", selecione o botão de opção "raw" e insira o JSON a seguir, substituindo os valores project.key, issuetype.name, summary e description conforme necessário:
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. Clique em "Send". O Jira responderá com o status 201 Created e todos os detalhes da issue recém-criada.
Etapa 5: Atualize uma issue
Para atualizar uma issue existente, usamos o método PUT:
- Altere o método HTTP para PUT e atualize a URL para apontar para a issue que deseja atualizar: https://your-domain.atlassian.net/rest/api/3/issue/ISSUE-KEY
No corpo da solicitação, inclua os campos que deseja atualizar, por exemplo:
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. Clique em "Send". O Jira responderá com o status 204 No Content para indicar que a atualização foi bem-sucedida.
Etapa 6: Pesquise issues usando JQL
Os poderosos recursos de pesquisa do Jira também podem ser acessados pela API REST usando JQL (Jira Query Language):
- Altere novamente o método HTTP para POST e atualize a URL para o endpoint de pesquisa: https://your-domain.atlassian.net/rest/api/3/search
No corpo da solicitação, inclua uma consulta JQL e quaisquer parâmetros adicionais:
json
Copy
{
"jql": "project = YOUR_PROJECT_KEY AND status = 'To Do' ORDER BY created DESC",
"fields": ["summary", "status", "assignee"],
"maxResults": 10
}
Essa consulta retornará as 10 issues criadas mais recentemente com o status 'To Do' do projeto especificado, incluindo apenas os campos de resumo, status e responsável.
- Clique em "Send". O Jira responderá com um array JSON de issues que correspondem aos seus critérios de busca.
Esses exemplos apenas mostram uma pequena parte do que é possível com a API REST do Jira. À medida que você se familiarizar com os endpoints e parâmetros disponíveis, poderá criar integrações cada vez mais complexas e poderosas.
Você pode automatizar o Jira sem usar API no Latenode
Como automatizar a criação e atualização de issues no Jira usando o Latenode
Uma das aplicações mais poderosas da API REST do Jira é a automação da criação e atualização de tarefas. Com o Latenode, você pode configurar fluxos sofisticados que criam e atualizam automaticamente tarefas no Jira com base em dados de fontes externas ou gatilhos específicos. Isso garante que as informações do seu sistema de gerenciamento de projetos permaneçam atuais e oportunas, aumentando a eficiência da equipe.
Por exemplo, você pode criar um fluxo que cria automaticamente uma nova tarefa no Jira quando uma mensagem de erro é recebida de um sistema de monitoramento, preenchendo todos os campos necessários e atribuindo a tarefa ao desenvolvedor adequado. Conforme as atualizações chegam, a tarefa pode ser atualizada automaticamente e, quando a issue for resolvida, ela poderá ser encerrada. Essa abordagem simplificada não apenas melhora o rastreamento de issues, como também economiza tempo da sua equipe, permitindo que ela se concentre na resolução de problemas em vez de administrá-los.
Você pode saber mais sobre este script e a integração com o Latenode neste artigo. A integração com o Latenode oferece alguns benefícios importantes:
- Facilidade de uso: O Latenode simplifica o processo de usar a API do Jira, facilitando que usuários não técnicos automatizem tarefas de gerenciamento de projetos.
- Preços flexíveis: Os usuários podem escolher entre diferentes planos do Latenode, com custos e recursos variados, para atender melhor às suas necessidades.
- Soluções abrangentes: A integração do Latenode com o Jira oferece acesso a uma ampla variedade de recursos de gerenciamento de projetos e rastreamento de issues.
- Personalização: Os usuários podem adaptar as integrações do Jira para atender às suas necessidades específicas, permitindo soluções de automação alinhadas aos objetivos de negócio.
Imagine que todos os e-mails importantes de um cliente se transformem automaticamente em uma tarefa no Jira. Com o Latenode, isso se torna realidade. Nossa plataforma garante a criação de uma nova tarefa no projeto correto, com campos preenchidos com base no conteúdo do e-mail, assegurando que nenhuma solicitação importante seja perdida.
Veja um exemplo de como um fluxo do Latenode automatiza a criação e as atualizações de tarefas do Jira com base em dados de e-mails recebidos de uma fonte externa.
Esta imagem mostraria uma representação visual do fluxo na interface da Latenode, com nós conectados representando cada etapa do processo, desde o recebimento do e-mail até a criação da tarefa no Jira.
Este é apenas um exemplo de como o Latenode pode transformar sua abordagem no uso da API do Jira com automação avançada. Na prática, os recursos da plataforma são praticamente ilimitados: você pode criar quaisquer automações necessárias para melhorar a eficiência do seu negócio. Seja distribuição automática de tarefas, envio de notificações, acompanhamento de indicadores-chave de desempenho ou qualquer outra atividade, o Latenode oferece as ferramentas para torná-las realidade.
Ao aproveitar o construtor visual de fluxos do Latenode e a integração perfeita com a API REST do Jira, você pode criar e implementar facilmente automações complexas, aumentando a eficiência do gerenciamento de projetos e acelerando os fluxos da sua equipe.
Se você precisar de ajuda ou orientação sobre como criar seu próprio script ou quiser replicar este, entre em contato com a nossa comunidade no Discord, onde estão os especialistas em automação Low-code.
Paginação, expansão e ordenação na API REST do Jira
Ao começar a trabalhar com conjuntos de dados maiores no Jira, você precisará saber como a API REST lida com paginação, expansão de recursos aninhados e ordenação de resultados.
Expansão
Muitos recursos do Jira contêm referências a outros recursos aninhados. Por exemplo, uma Issue contém referências ao seu Project, Issuetype, Creator, Reporter, Assignee, Comments, Attachments e muito mais. Por padrão, esses recursos aninhados são retornados como versões resumidas, contendo apenas alguns campos básicos e um link próprio para o recurso completo.
Se você precisar dos detalhes completos de um recurso aninhado, poderá usar o parâmetro de consulta expand para solicitar que o Jira inclua o recurso completo na resposta. Por exemplo, para incluir os detalhes completos do projeto e do responsável por uma issue:
GET .../rest/api/3/issue/ISSUE-KEY?expand=project,assignee
Você pode expandir vários recursos separando-os por vírgulas. Tenha em mente que as expansões podem aumentar significativamente o tamanho da carga da resposta, então use-as com cautela.
Paginação
Solicitações que podem retornar um grande número de resultados (como pesquisas JQL) são paginadas por padrão. A API retornará um número máximo de resultados por página (50 por padrão, mas personalizável até 100), junto com links para as páginas seguinte e anterior.
Você pode controlar a paginação usando os parâmetros startAt e maxResults:
- startAt: O índice do primeiro resultado a retornar (baseado em 0)
- maxResults: O número máximo de resultados a retornar por página
Por exemplo, para recuperar a segunda página de resultados com tamanho de página de 20:
GET .../rest/api/3/search?jql=project=YOUR_PROJECT_KEY&startAt=20&maxResults=20
Seu aplicativo precisará lidar com várias solicitações para recuperar todas as páginas de resultados.
Ordenação
Você pode controlar a ordem dos resultados usando o parâmetro orderBy, que aceita uma lista de campos separados por vírgulas para ordenação. Cada campo pode receber o prefixo - para indicar ordem decrescente.
Por exemplo, para ordenar issues pela data de criação em ordem decrescente e, em seguida, por prioridade em ordem crescente:
GET .../rest/api/3/search?jql=project=YOUR_PROJECT_KEY&orderBy=-created,priority
Nem todos os campos oferecem suporte à ordenação. Consulte a documentação do endpoint específico para verificar o que está disponível.
Exemplos de uso da API do Jira
Veja alguns exemplos mais avançados que demonstram o poder da API REST do Jira para operações em massa.
Criação/atualização em massa de issues a partir de CSV
Suponha que você tenha um arquivo CSV contendo dados de várias issues que deseja criar ou atualizar no Jira. Você pode usar uma ferramenta como o Postman para automatizar esse processo:
- No Postman, crie uma nova solicitação para o endpoint de criação ou atualização de issues.
Na guia Body, selecione o botão de opção "raw" e insira um modelo para os dados da sua issue, usando variáveis para os campos que virão do seu 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. Mude para a guia "Pre-request Script" e adicione o código para ler seu arquivo CSV e definir as variáveis correspondentes:
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. Na janela "Runner", selecione seu arquivo CSV como arquivo de dados e inicie a execução. O Postman criará uma nova solicitação para cada linha do CSV, substituindo as variáveis pelos valores do arquivo.
Essa é uma técnica poderosa para importar dados em massa para o Jira a partir de fontes externas.
Criação/atualização em massa de issues a partir de JSON
Se seus dados de origem já estiverem no formato JSON, você poderá usar o endpoint de criação/atualização em massa para processar várias issues em uma única solicitação:
POST https://your-domain.atlassian.net/rest/api/3/issue/bulk
O corpo da solicitação deve conter um array de objetos de criação/atualização de issues, cada um seguindo o mesmo formato de uma solicitação individual de criação/atualização de issue:
{
"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"]
}
}
]
}
Isso criará duas issues em uma solicitação: uma Task no projeto PROJ1 e um Bug no projeto PROJ2. Você pode incluir até 50 issues em uma única solicitação em massa.
O endpoint em massa também é útil para realizar transições, atualizações e exclusões em massa. Por exemplo, para mover várias issues para o status "Done":
{
"transition": {
"id": "31"
},
"issues": [
{"key": "ISSUE-1"},
{"key": "ISSUE-2"},
{"key": "ISSUE-3"}
]
}
Isso pressupõe que "31" seja o ID da sua transição "Done". Você pode encontrar as transições disponíveis para um tipo de issue pelo endpoint /rest/api/3/issue/{issueIdOrKey}/transitions.
Resumo
A API REST do Jira é uma ferramenta extremamente poderosa para integrar o Jira a outros sistemas, automatizar tarefas e expandir os recursos do Jira. Neste guia, abordamos os fundamentos da API, incluindo:
- A diferença entre as APIs Java e REST e quando usar cada uma
- As principais diferenças entre as APIs Cloud e Server/Data Center
- Como autenticar na API usando tokens de API ou Basic Auth
- Como fazer suas primeiras solicitações de API usando o Postman
- Criar, recuperar, atualizar e pesquisar issues
- Lidar com paginação, expansão e ordenação de resultados
- Casos de uso avançados, como criação/atualização em massa a partir de dados CSV e JSON
No entanto, exploramos apenas uma pequena parte do assunto. A API REST do Jira fornece endpoints para trabalhar com praticamente todos os aspectos do Jira, desde projetos e quadros até usuários e permissões. Ao criar suas integrações, consulte a documentação oficial da Atlassian para obter as informações mais atualizadas e completas.
Com a API REST do Jira no seu conjunto de ferramentas, as possibilidades do que você pode fazer com o Jira são quase infinitas. Seja criando um dashboard de relatórios personalizado, sincronizando dados com outro sistema ou automatizando fluxos complexos, a API fornece a flexibilidade e o poder necessários para tornar isso possível.
Você pode experimentar o Jira sem usar API no Latenode
