jira-rest-api

Jira REST API Client

A production-ready Python application for interacting with Jira’s REST API, built according to Jira’s Swagger/OpenAPI documentation with enterprise-grade features and security.

Features

Core Functionality

Production-Ready Features

Quick Start

📱 Personal/Internal Use (Single User Mode)

# Clone or download the project
cd jira-rest-api

# Install dependencies
pip install -r requirements.txt

# (Recommended) Run the interactive setup script
python setup.py
# This will automatically:
# - Collect your Jira credentials 
# - Generate a secure SECRET_KEY
# - Create the .env file

# Or manually copy environment template
copy .env.example .env
# Then edit .env with your details and generate a SECRET_KEY

Note: This application provides a web interface and Python library - there is no CLI tool. Use the web interface for interactive operations or the batch scripts for common tasks.

🏢 Production/Public Use (Multi-User OAuth)

For production deployment with OAuth authentication:

📋 See OAUTH_SETUP.md for complete setup guide

Quick Overview:

  1. Create OAuth app in Atlassian Developer Console
  2. Set APP_MODE=multi_user in environment
  3. Configure OAuth client ID/secret
  4. Deploy with individual user authentication

Benefits: Individual user permissions • Secure token management • Production scalability • Audit trails

2. Configuration

Edit the .env file with your Jira details, or let python setup.py create it for you:

JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-api-token
DEFAULT_PROJECT_KEY=YOUR_PROJECT_KEY
SECRET_KEY=your-secure-secret-key-for-flask

Getting your API Token:

  1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
  2. Click “Create API token”
  3. Give it a label and copy the token

Security Note: The SECRET_KEY is required for CSRF protection and secure sessions. Use a strong, random key in production.

3. Test Connection

python example.py

4. Start the Web Interface

python web_app.py
# Or use the batch script:
scripts\start_web.bat

The web app will be available at: http://localhost:5000

5. Use Batch Scripts (Windows)

You can use the scripts in the scripts/ folder for common tasks:

Scripts work from any directory and auto-activate the virtual environment.

6. Run the Test Suite

python test_suite.py

Usage

Web Interface

Start the web app with python web_app.py or scripts\start_web.bat and open http://localhost:5000 in your browser.

Features:

Security Features:

Available Batch Scripts

The application includes convenient Windows batch scripts in the scripts/ folder:

# Interactive launcher menu  
scripts\launcher.bat

# Start the web interface
scripts\start_web.bat

# Test connection to Jira
scripts\test_connection.bat

# Run example demonstration
scripts\run_example.bat

# Search recent issues
scripts\search_issues.bat

# Test pagination functionality
scripts\test_pagination.bat

All scripts automatically activate the virtual environment and work from any directory.

Python Library Usage

from jira_client import JiraAPIClient

# Initialize client (reads from .env file)
client = JiraAPIClient()

# Or initialize with explicit parameters
client = JiraAPIClient(
    base_url="https://your-domain.atlassian.net",
    email="your-email@example.com",
    api_token="your-api-token"
)

# Test connection
if client.test_connection():
    print("Connected successfully!")

# Get current user
user = client.get_current_user()
print(f"Logged in as: {user['displayName']}")

# List projects
projects = client.get_projects()
for project in projects:
    print(f"- {project['key']}: {project['name']}")

# Search issues with token-based pagination
issues = client.search_issues(
    jql="project = PROJ AND status = 'To Do'",
    max_results=10,
    fields=['summary', 'status', 'assignee']
)

# Create an issue
new_issue = client.create_issue(
    project_key="PROJ",
    summary="New issue via API",
    description="This issue was created using the API",
    issue_type="Task"
)
print(f"Created issue: {new_issue['key']}")

# Add comment and attachment
client.add_comment(new_issue['key'], "Comment via API")
client.add_attachment(new_issue['key'], "path/to/file.pdf")

# Get issue details
issue = client.get_issue("PROJ-123")
print(f"Issue: {issue['fields']['summary']}")

# Transition issue
transitions = client.get_issue_transitions("PROJ-123")
# Find the transition ID you want and use it
client.transition_issue("PROJ-123", "transition-id")

# Bulk operations with progress tracking
def progress_callback(current, total, message):
    print(f"Progress: {current}/{total} - {message}")

client.bulk_create_links(
    source_issue="PROJ-1",
    target_issues=["PROJ-2", "PROJ-3", "PROJ-4"],
    link_type="relates to",
    progress_callback=progress_callback
)

Production Features

The client includes enterprise-ready features:

API Coverage

All major Jira REST API v3 endpoints are implemented with production-ready features:

Examples

Quick Demo

Run the example script to see the client in action:

python example.py

This will demonstrate:

Batch Script Examples

Use the convenient batch scripts for common operations:

# Interactive menu with all options
scripts\launcher.bat

# Quick connection test
scripts\test_connection.bat

# Demo the API capabilities
scripts\run_example.bat

# Search for recent issues
scripts\search_issues.bat

Error Handling & Reliability

The application includes enterprise-grade error handling and reliability features:

Error Handling

Reliability Features

Advanced Usage

Custom Fields

# Create issue with custom fields
custom_fields = {
    'customfield_10001': 'Custom value',
    'customfield_10002': {'value': 'Option 1'}
}

client.create_issue(
    project_key="PROJ",
    summary="Issue with custom fields",
    description="Description",
    **custom_fields
)

Token-Based Pagination

The client uses Jira’s modern token-based pagination for efficient large dataset handling:

# Example: Paginate through issues
token = None
while True:
    results = client.search_issues(
        jql="project = PROJ",
        max_results=50,
        next_page_token=token
    )
    issues = results.get('issues', [])
    if not issues:
        break
    for issue in issues:
        print(issue['key'])
    token = results.get('nextPageToken')
    if not token:
        break

The web interface includes session-based pagination with forward/backward navigation and token management.

Bulk Operations

Enhanced bulk operations with progress tracking and error resilience:

# Update multiple issues with progress tracking
def update_progress(current, total, message):
    print(f"Progress: {current}/{total} - {message}")

issue_keys = ['PROJ-1', 'PROJ-2', 'PROJ-3']

# Bulk link creation with automatic retry
client.bulk_create_links(
    source_issue="PROJ-1",
    target_issues=issue_keys,
    link_type="relates to",
    progress_callback=update_progress
)

# Individual updates with automatic retry on rate limits
for key in issue_keys:
    client.update_issue(key, {
        'summary': 'Updated summary',
        'priority': {'name': 'High'}
    })
    # Automatic exponential backoff on 429 responses

Development & Testing

Current Test Suite

Run the current test suite (API, pagination, templates, web app):

python test_suite.py

If any tests fail, check your .env configuration and ensure the web app is running for web tests.

Logging

The application creates structured log files:

Dependencies

Key production dependencies (from requirements.txt):

License

This project is open source and available under the MIT License.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Recent Updates (October 2025)

Security & Production Readiness

Enhanced Features

Reliability Improvements

Support

For issues and questions:

  1. Check the application logs in jira_web_app.log
  2. Review the Jira REST API documentation
  3. Verify your .env configuration
  4. Create an issue in this repository

Jira API Documentation

This client follows the official Jira REST API documentation:

The client is designed to work with both Jira Cloud and Jira Server instances.