Apresentação realizada na reunião de 26 de junho de 2019 do Atlassian User Group de São Paulo. Demonstração de como a interface REST dos produtos da plataforma Atlassian podem ser considerados como alternativas aos APPS e a tarefas manuais pela interface Web. Ao final há um exemplo onde a opção de utilizar a interface REST economizou tempo e dinheiro e entregou o trabalho feito

1. JOÃO GALDINO M. DE SOUZA | SENIOR PRINCIPAL | INFOSYS CONSULTING
Explorando a API Rest
Jira Cloud

2. Agenda
Motivação
Por onde começo?
Autenticação
Algumas chamadas interessantes
Exemplo de uso

3. Introdução
João Galdino M. de Souza
Infosys Consulting
Senior Principal
Experiência como Jira Admin e uso de
REST API no Jira software, Jira
Service Desk e Apps em versão
Server (Saraiva) e Jira Service Desk
em versão cloud (Infosys)

4. Essa apresentação não é
exaustiva sobre REST API e
expõe algumas lições que
aprendi utilizando esta
interface

5. Motivação
Usar API Rest, por quê?

6. Por que usar REST API?
Adicione seu motivo
pessoal aqui
Curiosidade Nerd
(como matar o tédio)
“Preguiça” de
executar tarefas
manualmente
Interagir de forma sistemática com
o Jira
Automatizar tarefas repetitivas
Integrações entre instâncias
diferentes de Jira com controle
mais granular
Economia em relação aos APPs
No Jira Cloud não há acesso ao file
system ou a Base de Dados

7. Por onde começo?
Escolha suas armas ferramentas

8. Que cliente utilizar?
Não se esqueça de
Requisitos não
funcionais
Desempenho
Escalabilidade
Robustez
Segurança
Aplicativo (Curl, SOAP UI) ou
programa (Java, C, Go, Java script,
Powershell, Perl, etc)?
Linguagem formal ou script?
Pense na sua plataforma (SO,
ambiente, etc)
Pense em suas competências e
habilidades

9. Espaço API REST do Jira
Confluence
Cloud
REST API
Jira Cloud
REST API
Jira SD
Cloud
REST API
Jira
Software
Cloud
REST API
Tempo
Timesheet
REST API
Other Apps
Cloud*
Jira Server
REST API
Jira SD
Server
REST API
Jira
Software
Server
REST API
Riada
Insight
REST API
Other Apps
Server*
Outros
produtos
Atlassian

10. A API REST do Jira – Verifique qual utilizar
Jira Cloud
REST API
Issues
Projects
Users
Groups
Filters
Workflows
Application Roles
Audit Records
Avatars
Dashboards
JQL
Permissions
Tasks
Others
Jira SD Cloud
REST API
Requests
Request types
Customer
Knowledge Base
Service Desk
Jira Software
Cloud REST API
Backlog
Board
Epic
Issue *
Sprint
Deployments
Builds
Feature Flags
Development Information

11. HTTPS://DEVELOPER.ATLASSIAN.COM/CLOUD/
Documentação
extensa e
completa
Lembre-se de
acessar a versão
que você está
usando

12. DOCUMENTAÇÃO APPS – GOOGLE “<NOME APP> REST API JIRA”
Nem sempre a
documentação é
boa e completa
Tempo
timesheet API

13. Autenticação/
Autorização
Como me identificar?

14. Como me identificar?
O usuário que
será utilizado
para o acesso via
REST API deve
possuir
permissão para
executar as ações
necessárias no
Jira
Connect (para apps)
OAUTH
(para apps que não usam o connect e para
REST)
Basic authentication
Diferente da versão Server, é necessário gerar
um Token para ser utilizado como senha
durante o processo de autenticação
Se estiver usando a versão Server, utilizar o par
usuário e senha normalmente

15. GERANDO TOKEN PARA USO EM REST API
HTTPS://ID.ATLASSIAN.COM/MANAGE/API-TOKENS
Acessar a URL
acima com o
usuário que fará
os acessos
REST
Este token será
utilizado como a
senha do
usuário em
Basic
Authentication

16. $cred=get-credential -Message "Enter you
username and password to access Jira Cloud"
$user = $cred.username
$pass =
[Runtime.InteropServices.Marshal]::PtrToString
Auto([Runtime.InteropServices.Marshal]::Secure
StringToBSTR($cred.password))
$pair = "$($user):$($pass)"
$encodedCreds =
[System.Convert]::ToBase64String([System.Text.
Encoding]::ASCII.GetBytes($pair))
$authorization = "Basic $encodedCreds"
Lendo
credencial
de usuário
Lendo usuário
e senha
Montando string
para basic
authentication
Codificando
com BASE64
Powershell

17. Em uma janela Powershell com o usuário que será utilizado o
programa que fará uso da credencial criar um arquivo que irá
armazenar a credencial criptografada
PS C:> read-host -assecurestring | convertfrom-securestring |
out-file C:cred.txt
No Programa que fará uso da credencial, pode-se ler a credencial
criptografada com o seguinte commando
PS C:> $password = get-content C:cred.txt | convertto-
securestring
Como
armazenar
credenciais
Windows
Armazenar
Credenciais
Windows
Powershell
Powershell

18. $user = “username”
$pass = get-content C:cred.txt | convertto-
securestring
$pair = "$($user):$($pass)"
$encodedCreds =
[System.Convert]::ToBase64String([System.Text.
Encoding]::ASCII.GetBytes($pair))
$authorization = "Basic $encodedCreds"
Utilizando
credencial
armazenada
Lendo usuário
e senha
Montando string
para basic
authentication
Codificando
com BASE64
Powershell

19. Criando issues
No Jira Core

20. Descobrindo os tipos de Issues que podem
ser criados em um projeto
There is
a REST
for that!
Get create issue
metadata
GET /rest/api/3/issue/createmeta
Parametros
ProjectId=1000[,1000]*
ProjectKeys=KEY1[,KEY2]*
Retorno: Json com lista de
Issuetypes

21. SOAP UI PARA TESTAR AS REQUISIÇÕES EM DESENVOLVIMENTO
Utilize SOAP UI
para obter todos
os IDs e
informações
para gerar as
requisições
necessárias
Ex:
ProjectIds,
UserID,
Issuetypes,
customfields, etc

22. ...
"issuetypes":[
{
"self":
"https://xxx.atlassian.net/rest/api/3/issuety
pe/10500",
"id": "10500",
"description": "Descrição do Issuetype",
"iconUrl": "https://xxx.atlassian.net/...",
"name": "Investigation",
"subtask": false
},
...
Retorno
Precisamos do
id do issue type

23. {
"fields": {
"project": { "id": "1000“ },
"summary": "REST API Example Task 1",
"issuetype": { "id": “10500“ },
"assignee": { “id": “99:01902...” },
"reporter": { “id": "99:01902..." },
"priority": { "id": "1" },
"description": "This is an example
task created through the REST API."
}
}
Criando
Issue
POST
/rest/api/3/issue
JSON no corpo da
requisição
Após GPDR é
necessário usar id do
usuário e não
username

24. {
"id": "10000",
"key": "TST-24",
"self":
"http://xxx.atlassian.net/rest/api/3/issue/10
000",
"transition": {
"status": 200,
"errorCollection": {
"errorMessages": [],
"errors": {}
}
}
}
Retorno
JSON com Issue
criada
Sempre
verifique os
status e
mensagens de
erros

25. Adicionando
comentários em uma
issue

26. {
"visibility": {
"type": "role",
"value": "Administrators"
},
"body": {
"type": "doc",
"version": 1,
"content": [
{
"type": "paragraph",
"content": [
{
"text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque eget
venenatis elit. Duis eu justo eget augue iaculis fermentum. Sed semper quam laoreet nisi egestas
at posuere augue semper.",
"type": "text"
}
]
}
]
}
Incluindo
comentários
POST /rest/api/3/issue/<IssueKey>/comment
Parâmetros em
JSON no corpo
da requisição

27. Transições
Como executar transições com REST API

28. { "expand": "transitions",
"transitions": [
{
"id": "111",
"name": "Finish coding",
"to": {
"self": "https://xxx.atlassian.net/rest/api/3/status/12019",
"description": "",
"name": "Ready for Review",
"id": "12019",
"statusCategory": {
"self": "https://xxx.atlassian.net/rest/api/3/statuscategory/4",
"id": 4,
"key": "indeterminate",
"colorName": "yellow",
"name": "In Progress"
}
},
"hasScreen": true,
"isGlobal": false,
"isInitial": false,
"isConditional": true
Pesquisando
transições
disponíveis
GET
/rest/api/3/issue/
{issueIdOrKey}/t
ransitions
GET
/rest/api/3/issue/
TST-
24/transitions
RETORNO >

29. {
"transition“: {
"id": "111",
}
}
Pode ser necessário incluir outros
campos na transição, de acordo com a
configuração do workflow no Jira
Executando
transição
POST
/rest/api/3/issue/
{issueIdOrKey}/t
ransitions
POST
/rest/api/3/issue/
TST-
24/transitions
Parâmetros no
JSON

30. Pesquisando Issues
Usando JQL

31. {
"expand": [ "names", "schema","operations"
],
"jql": "project = TST",
"maxResults": 15,
"fieldsByKeys": false,
"fields": [
"summary",
"status",
"assignee"
],
"startAt": 0
}
Pesquisando
issues com
JQL
POST
/rest/api/3/search
Parâmetros de
busca no corpo
da requisição
Paginação com
campos StartAt e
maxResults

32. Exemplo
Colocando algumas chamadas para trabalhar para mim...

33. Fazer backup de todos os issues de um
projeto incluindo os anexos
A opção de compartilhar o resultado de um filtro em DOC
exporta todo o conteúdo das issues, porém não exporta os
anexos.
Opções:
1) Adquirir um APP que permita exportar os anexos
2) Desenvolver um script que use API REST do Jira para
exportar os anexos
3) Entrar em cada um dos issues (413 no total) e fazer o
download de todos os anexos (estimativa de ~8 horas)
APP suportado na
versão do Jira?
(somente 4 de 10 para
Cloud)
APP faz a função
desejada? Os apps
pesquisados não fazia
o download e sim
colocavam links para
download em um PDF

34. Escolhida Opção 2
Construir um programa para
exportar todos os anexos
via REST API

35. JQL SEARCH
Última
página?
Não
FIM
GET ISSUE
ATTACHMENT
Anexos?
DOWNLOAD
ATTACHMENT
CREATE
FOLDER
Sim
última
issue?
Não
SIM
NÃO

36. Pesquisar todos os
issues do cliente
usando JQL que
devem ser exportados
(fazer paginações
para obter todos os
issues)
{
"jql": "project = “XX" AND issuetype !=
Monitoramento AND status not in (Cancelado)
ORDER BY component",
"maxResults": 50,
"fieldsByKeys": false,
"fields": [
"summary",
"status",
"assignee"
],
"startAt": 0
}
JSON usado na pesquisa
Paginação de 50 em 50
POST /rest/api/3/search
Retorno é um JSON com
a lista de issues para a
página

37. Pesquisar todos os
issues do cliente
usando JQL que
devem ser exportados
(fazer paginações
para obter todos os
issues)
Paginação de 50 em 50, o JSON de retorno indica a quantidade
de issues retornado, é esse o valor que precisa ser controlado
para consumir toda o resultado da pesquisa, no caso será
necessário executar 9 buscas para obter todas as issues

38. {
"id": "43857",
"self": "https://xxx.atlassian.net/rest/api/3/issue/43857",
"key": “<ID>",
"fields": {"attachment": [
{
"self": "https://xxx.atlassian.net/rest/api/3/attachment/45231",
"id": "45231",
"filename": “nome_do_arquivo.pdf",
"author": {…}
"created": "2018-11-13T17:32:57.684-0200",
"size": 44991,
"mimeType": "application/pdf",
"content": "https://xxx.atlassian.net/secure/attachment/45231/nome_do_arquivo
}, …
JSON resultado (resumido para no slide)
GET /rest/api/3/issue/<ID>?fields=attachment
DICA: Fazendo a consulta
com o parâmetro fields é
possível restringir a resposta
para conter apenas o campo
Attachments (economiza banda
e processamento)
Fazer uma consulta REST
solicitando o campo attachment

39. "content":
"https://xxx.atlassian.net/secure/attachment/45231/nome_do_arquivo.pdf"
"filename": “nome_do_arquivo.pdf"
GET /rest/api/3/attachment/<ID>
Para cada anexo de cada issue,
fazer o download
Utilizando o endereço obtido no campo content de cada um dos attachments e
o nome do arquivo original, pode-se fazer o download com um simples GET
no endereço e renomear o objeto

40. Script finalizado
~75 linhas em Powershell
2.639 arquivos de 413 issues
+800MB de anexos
Execução em minutos

41. Lições aprendidas
Entenda e desenhe o
workflow de como
funcionará a interação
com a API Rest do Jira
Cuidado para não
automatizar apenas
uma parte do workflow
Utilize ferramenta como
o SOAP UI para
explorar as chamadas
REST na fase de
desenvolvimento
Cuidado na
Autenticação,
autorização e
permissões. Escolha
bem qual usuário
utilizar
Atenção com novas
versões do Jira,
causam mudanças no
comportamento da API
REST (pouco comum
mas com alto impacto)
Atenção com a escolha
do cliente que irá
consumir a interface
REST

42. JOÃO GALDINO M. DE SOUZA | SENIOR PRINCIPAL | INFOSYS CONSULTING
Thank you!