Exploring Jira REST API
Jira is a powerful project management tool that can be extended and integrated with other systems through its RESTful API. This API allows developers to interact with Jira programmatically, enabling tasks such as creating issues, searching for issues, updating project information, and more.
Basic Concepts
The Jira REST API is structured around resources, which are the entities you can interact with (e.g., issues, projects, users). Each resource has a corresponding endpoint that you can use to perform various operations like GET, POST, PUT, and DELETE.
Authentication
To interact with the Jira API, you need to authenticate. Jira supports basic authentication, OAuth, and API tokens. For simplicity, this guide will use basic authentication with an API token.
Endpoints
1. Creating an Issue
The /rest/api/3/issue endpoint is used to create issues in Jira.
JavaScript (Fetch API)
const createIssue = async () => {
const url = 'https://your-domain.atlassian.net/rest/api/3/issue';
const body = JSON.stringify({
fields: {
project: {
key: 'PROJECT_KEY',
},
summary: 'REST ye merry gentlemen.',
description: 'Creating an issue via POST.',
issuetype: {
name: 'Bug',
},
}
});
const response = await fetch(url, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic ' + btoa('your-email@example.com:your-api-token')
},
body: body
});
const data = await response.json();
console.log(data);
};
createIssue();
Python (Requests Library)
import requests
from requests.auth import HTTPBasicAuth
import json
url = 'https://your-domain.atlassian.net/rest/api/3/issue'
auth = HTTPBasicAuth('your-email@example.com', 'your-api-token')
headers = {
"Accept": "application/json",
"Content-Type": "application/json"
}
payload = json.dumps({
'fields': {
'project': {
'key': 'PROJECT_KEY',
},
'summary': 'REST ye merry gentlemen.',
'description': 'Creating an issue via POST.',
'issuetype': {
'name': 'Bug',
}
}
})
response = requests.request(
"POST",
url,
data=payload,
headers=headers,
auth=auth
)
print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))
2. Searching Issues
The /rest/api/3/search endpoint allows you to search for issues using JQL (Jira Query Language).
JavaScript (Fetch API)
const searchIssues = async () => {
const url = 'https://your-domain.atlassian.net/rest/api/3/search?jql=project=PROJECT_KEY';
const response = await fetch(url, {
method: 'GET',
headers: {
'Authorization': 'Basic ' + btoa('your-email@example.com:your-api-token')
}
});
const data = await response.json();
console.log(data);
};
searchIssues();
Python (Requests Library)
import requests
from requests.auth import HTTPBasicAuth
url = 'https://your-domain.atlassian.net/rest/api/3/search?jql=project=PROJECT_KEY'
auth = HTTPBasicAuth('your-email@example.com', 'your-api-token')
headers = {
"Accept": "application/json"
}
response = requests.request(
"GET",
url,
headers=headers,
auth=auth
)
print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))
3. Updating an Issue
The /rest/api/3/issue/{issueIdOrKey} endpoint is used to update an existing issue.
JavaScript (Fetch API)
const updateIssue = async (issueId, newSummary) => {
const url = `https://your-domain.atlassian.net/rest/api/3/issue/${issueId}`;
const body = JSON.stringify({
fields: {
summary: newSummary
}
});
const response = await fetch(url, {
method: 'PUT',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic ' + btoa('your-email@example.com:your-api-token')
},
body: body
});
const data = await response.json();
console.log(data);
};
updateIssue('ISSUE_ID', 'Updated summary via PUT');
Python (Requests Library)
import requests
from requests.auth import HTTPBasicAuth
import json
issue_id = 'ISSUE_ID'
url = f'https://your-domain.atlassian.net/rest/api/3/issue/{issue_id}'
auth = HTTPBasicAuth('your-email@example.com', 'your-api-token')
headers = {
"Accept": "application/json",
"Content-Type": "application/json"
}
payload = json.dumps({
'fields': {
'summary': 'Updated summary via PUT'
}
})
response = requests.request(
"PUT",
url,
data=payload,
headers=headers,
auth=auth
)
print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))
Conclusion
The Jira REST API provides a robust way to integrate Jira with other systems and automate repetitive tasks. Whether you’re building custom reports, integrating with CI/CD pipelines, or automating issue creation, the Jira API can be a valuable tool in your development toolkit.
