Working with API
- Kamil Parzyjagła
- Anna Kwaśny
- Paweł Albecki (Deactivated)
Table of contents
Introduction
Our plugin allows you to change its data via Atlassian API. We use the properties of the issue so you can get, update, delete or create data outside of the plugin UI.
You can preview the data by making a GET request to: https://{ site-url }.atlassian.net/rest/api/2/issue/{ issue.id }/properties/sd-checklists-0
PUT requests are also made to the same endpoint.
If you have a lot of checklists, you may need to call GET
https://{ site-url }.atlassian.net/rest/api/2/issue/{ issue.id }/properties
to check if there are properties like sd-checklists-1, sd-checklists-2 that contain checklists that did not fit into sd-checklists-0
If your project permission is not set to "anyone" you will need an API Token. You can generate it here: https://id.atlassian.com/manage/api-tokens
After acquiring it you will be able to use the API as long as your account has sufficient permissions.
Below you can find examples using curl and postman, but first, let's check the checklist data structure.
Data structure:
We store an array of checklists for every issue separately. Each checklist has an id, name, and an array of items.
You should always set the version to 1.0.0. It is here to help us detect the version of the checklist our client is using.
Field responsibility:
- version - it allows us to detect what version of the checklist you are using. Leave it at 1.0.0.
- checklists - array of checklists in issue:
- id - id of checklist
- name - name of checklist
- items - tasks in checklist:
- name - name of the task
- required - currently not in use
- completed - Boolean if the task was completed or not
- status - one of the statuses (check settings to add more, edit, delete)
- user - latest user who edited the item
- date - latest time the item was edited
JSON Schema:
{
"definitions": {},
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://example.com/root.json",
"type": "object",
"title": "The Root Schema",
"properties": {
"version": {
"type": "string",
"title": "Version",
"description": "Version of the checklist. Currently at 1.0.0. This value should be always used.",
"default": "",
"examples": [
"1.0.0"
]
},
"checklists": {
"type": "array",
"title": "Checklists",
"description": "Array of checklists in the issue.",
"default": null,
"items": {
"type": "object",
"title": "Checklist",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"title": "The Name Schema",
"default": "",
"examples": [
"Example to do"
]
},
"items": {
"type": "array",
"title": "Items",
"description": "Tasks in the checklist",
"default": null,
"items": {
"type": "object",
"title": "Items",
"description": "Task in the checklist",
"default": null,
"required": [
"name",
"required",
"completed",
"status",
"user",
"date"
],
"properties": {
"name": {
"type": "string",
"title": "The Name Schema",
"default": "",
"examples": [
"<p>task 1</p>"
]
},
"required": {
"type": "boolean",
"title": "Required",
"description": "currently not in use",
"default": false,
"examples": [
true
]
},
"completed": {
"type": "boolean",
"title": "Completed",
"description": "Check if the task was completed or not",
"default": false,
"examples": [
true
]
},
"status": {
"type": "integer",
"title": "Status",
"description": "Indicate one of the statuses",
"default": 0,
"examples": [
0
]
},
"user": {
"type": "string",
"title": "User",
"description": "Id of latest user who edited the item",
"default": "",
"examples": [
""
]
},
"date": {
"type": "string",
"title": "date",
"description": "Time of the latest update",
"default": "",
"examples": [
"2019-08-13T13:18:24.046Z"
]
}
}
}
}
}
}
}
}
}
JSON Data:
{
"version":"1.0.0",
"checklists":[
{
"id":0,
"name":"Example to do",
"items":[
{
"name":"<p>task 1</p>",
"required":true,
"completed":true,
"status":0,
"user":"{ user id }",
"date":"2019-08-13T13:18:24.046Z"
}
]
}
]
}
Endpoints:
Issue screen:
https://{ site-url }.atlassian.net/rest/api/2/issue/{ issue.id }/properties/sd-checklists-0 - read/update/delete the checklist
Settings screen:
https://{ site-url }.atlassian.net/rest/api/2/project/{ project.id }/properties/soldevelo-checklists-settings - enable/disable checklists for the project
Manage templates screen:
https://{ site-url }.atlassian.net/rest/api/2/project/{ project.id }/properties/default-templates - add/remove default template to the project
Other:
Templates and other settings are currently unavailable. You can not edit them outside of the app UI and currently we are not planing to change this behavior.
Examples with Curl:
How to retrieve checklists:
To retrieve the checklist for an issue you need to provide email and API key from account with sufficient permissions as well as url with 2 variables: your "site-url" and the "issue id".
curl -u { your email }:{ your API token } https://{ site-url }.atlassian.net/rest/api/2/issue/{ issue.id }/properties/sd-checklists-0
How to add/update checklist:
When updating the checklist you should get the current object, edit it to your liking and then send it back also as an whole object. You shouldn't post for example only one item which you edited.
Some examples:
If you want to mark the task as done then change "completed" field of an appropriate item.
If you want to rename the task then change the "name" field of an appropriate item.
If you want to add new task then add it to "items" array.
If you want to add new checklist then add it to "checklist" array with new unique id.
Here is how you can make PUT request with curl. Adding and updating is made using the same request.
curl -X PUT -H "Content-Type: application/json" -u { your email }:{ your API token } https://{ site-url }.atlassian.net/rest/api/2/issue/{ issue.id }/properties/sd-checklists-0 -d '{
"version":"1.0.0",
"checklists":[
{
"id":0,
"name":"Example to do",
"items":[
{
"name":"<p>task 1</p>",
"required":true,
"completed":true,
"status":0,
"user":"{ user id }",
"date":"2019-08-13T13:18:24.046Z"
},
{
"name":"<p>task 2</p>",
"required":false,
"completed":true,
"status":0,
"user":"{ user id }",
"date":"2019-08-13T13:18:44.988Z"
},
{
"name":"<p>task 3</p>",
"required":false,
"completed":false,
"status":0,
"user":"{ user id }",
"date":"2019-08-08T13:30:29.643Z"
}
]
}
]
}'
How to remove checklist:
To delete all checklist you can make a PUT request with empty data.
curl -X PUT -H "Content-Type: application/json" -u { your email }:{ your API token } https://{ site-url }.atlassian.net/rest/api/2/issue/{ issue.id }/properties/sd-checklists-0 -d '{}'
Examples with Postman:
How to retrieve data:
To make a GET request you need to set a basic auth with your email and API token. The header will be generated automatically. Check the screenshot below for an example:
How to update data:
To make a PUT request you need to set a header, basic auth with your email and API token, and body with data. Check the screenshot below for an example:
