Swagger: Rest API & Integrations
- Vasyl Krokha (Unlicensed)
- Yuri Lapin
- Yuri (Unlicensed)
Renaming “Releases“ to “Packages“
As of June, 2024 we re renaming “Releases“ to “Packages“ to be aligned with our Cloud products and avoid long running confusion with “Releases“ in Jira. Some areas of our App will still have release notion/naming due to technical limitations, namely:
API roots will still be called / release / while tags and descriptions in Swagger changed to packages
Webhook injectable variables will be called entity.*
Release notes injectable variables will be called release.*
JQL functions will still be called versionsOfReleases.. & issuesOfReleases..
Topics
In addition to outgoing communication via Automation via Outcoming WebHooks we also support incoming calls via our Rest API.
Where to find our API?
Navigate to top right corner of Release Management iframe to find an API icon.
Click on it to open a standard Swager Open API UI in new tab.
What possibilities APIs can give me?
We “eat our own dog food here“ and use the same API to connect frontend and backend of our App. So, theoretically most of the things you can do via UI can be done via API calls.
Please reach out to our support team for advice on specific use cases.
How I can get a Token to access API?
To access our Rest API you would need to get a personalized Token. This will provide your context to our API to execute. Thus, your permissions will be verified to execute specific API end points.
To get on, click on your Avatar/Photo in Jira and select Profile
Select Personal Access Tokens and click Create Token.
While creating a Token please pay attention to the expiration date. Suggest to use shorter timeframe of one off tokens to extract data or smth. If you plan to use Examples of Release Automation (also via Jira Automation) suggestion is to user longer living tokens.
Specify Token Name and click Create.
Find out more about personalized tokens here Using Personal Access Tokens | Atlassian Support | Atlassian Documentation.
How to execute calls to our APIs?
There are multiple ways to execute API calls depending on your use cases. We will show it here based on Postman example.
So, to execute GetBoard call you would need to run Postman and specify the following parameters:
URL: <https://<YOUR_JIRA_URL>/rest/release-management/1.0/board/BoardID>
Header: <Name: Authorization, Value: Bearer “Personalized Token Created on previous step”>
Method: <GET>
Request Body: Empty
Use cases
Integration with PowerBI, EasyBI, Tableau, etc.
If you want to extract Release Management App data to transform and load into one of the famous BI solutions (like PowerBI, EasyBI, Tableau, etc.) our APIs provides such flexibility.
Probably GetBoard end point is what you need:
Integration with CI/CD tools
Integration with CI/CD tools are usually bi-directional - outcoming and incoming.
An example of outcoming integration is most probably executing build or running certain pipeline when version is moved to specific destination column. Such flexibility could be achieved via Automation via Outcoming WebHooks.
If you trigger builds/pipelines manually or with some other automation you might want to
move version into some specific column after the build
specify environment where the version is available, incl. specific build number
provide some additional comments into version for audit log
amend version custom properties with a link to build to test
etc.
For all the above incoming calls you would need to use our Rest API and therefore the above sections of this page will be very helpful.
Integration with Jira Automation
Integration with JIra Automation is also bi-directional. From our experience most the cases are connected with aligning statuses of Jira issues and versions/packages, e.g.:
move version in progress when at least one encompassing issue is in progress
move version to done when all issues are done, or update issues to done when version is moved to done (either independant or in scope of package)
mark all Epics as Released when versions/package is Released.
etc.
Same story here - use Automation via Outcoming WebHooks to run Automation in Jira as post action in Release management or use our Rest API to execute some actions in Release Management in scope of Jira Automation rule.
Find out more details in Examples of Release Automation (also via Jira Automation) section of this documentation.
Version details endpoint
Coming soon if not already
Sometimes you need to retrieve version details and associated data w/o a need to load a complete board (using /board endpoint). Therefore we created the following handy API endpoint
Example data output:
{
"versionType": "VERSION",
"id": 12622,
"name": "Online Banking Version 2.0",
"description": "",
"archived": false,
"milestones": [],
"customFields": [
{
"id": 89,
"customFieldId": 69,
"entityType": "VERSION",
"entityId": 12622,
"value": "John",
"type": "string",
"name": "Driver"
},
{
"id": 77,
"customFieldId": 72,
"entityType": "VERSION",
"entityId": 12622,
"value": "Planned",
"type": "string",
"name": "Release Type"
}
],
"releases": [
{
"id": 801,
"name": "[BankFlow Blitz] PI 2",
"description": "",
"archived": false,
"columnId": 1028,
"startDate": "2023-10-02",
"releaseDate": "2023-11-10",
"versions": [
1422,
1423,
1424,
1425,
1426,
1427,
1428,
1429,
1430,
1431,
1432,
1433,
1434,
1435
],
"virtualVersions": [
1440,
1441,
1442,
1443,
1444,
1436,
1437,
1438,
1439
]
}
],
"column": {
"id": 1033,
"name": "🌀 Integration",
"type": "version",
"isDefault": false,
"isReleased": false,
"sequence": 4,
"reqReleaseDate": false,
"default": false,
"released": false
},
"environments": [
{
"id": 539,
"type": "DEVELOPMENT",
"buildNumber": "RC 111.2",
"name": "Development Sandbox OnDemand"
},
{
"id": 540,
"type": "STAGING",
"buildNumber": "RC 116.2",
"name": "Gamma Staging environment"
},
{
"id": 541,
"type": "INTEGRATION",
"buildNumber": "RC 116.2",
"name": "Omega Integration environment"
}
],
"assignee": null,
"watchers": [],
"tags": [],
"startDate": "2023-10-02",
"releaseDate": "2023-10-20",
"released": false,
"projectId": 11004
}