jira-api

What this skill does

# Jira REST API v3 Documentation

## Purpose

This skill provides authoritative guidance on using the Atlassian Jira REST API v3, including endpoint references, authentication methods, request/response formats, query languages, and best practices for programmatic Jira automation and integration.

## Quick Start

To get started with the Jira API:

1. **Authenticate**: Use Basic Auth with API token (email:token in base64)
2. **Make a request**: `GET /rest/api/3/issue/{issueIdOrKey}`
3. **Parse response**: Standard JSON with issue details, changelog, and custom fields

For the project's `JiraClient` class:
```python
from jira_tool.client import JiraClient

client = JiraClient()
issue = client.get_issue("PROJ-123")
```

## Instructions

### Step 1: Understanding Jira REST API v3 Basics

The Jira REST API v3 is the current standard API for Jira Cloud. Key characteristics:
- **Base URL**: `https://{jira-instance}.atlassian.net/rest/api/3/`
- **Authentication**: Basic Auth with API tokens (not passwords)
- **Data Format**: JSON for requests and responses
- **Versioning**: v3 is the latest; v2 is deprecated

**Official Documentation**: https://developer.atlassian.com/cloud/jira/platform/rest/v3/

### Step 2: Authentication Methods

#### Basic Auth with API Token (Recommended)

This is what the project uses. Steps:
1. Generate API token in Jira user settings (atlassian account)
2. Create header: `Authorization: Basic {base64(email:token)}`
3. Add `Accept: application/json` and `Content-Type: application/json` headers

```python
from base64 import b64encode

email = "[email protected]"
api_token = "your-api-token"
credentials = f"{email}:{api_token}"
auth_header = b64encode(credentials.encode()).decode()
headers = {
    "Authorization": f"Basic {auth_header}",
    "Accept": "application/json",
    "Content-Type": "application/json",
}
```

The `JiraClient` class handles this automatically:
```python
client = JiraClient(
    base_url="https://company.atlassian.net",
    username="[email protected]",
    api_token="token-from-atlassian"
)
```

#### OAuth 2.0

For third-party applications:
- Requires OAuth app registration
- More complex but better for user-facing integrations
- See references/reference.md for OAuth flow details

### Step 3: Core API Endpoints

Common endpoints you'll use frequently:

**Issue Operations**
- `GET /rest/api/3/issue/{issueIdOrKey}` - Get issue details
- `POST /rest/api/3/issues` - Create issue
- `PUT /rest/api/3/issue/{issueIdOrKey}` - Update issue
- `DELETE /rest/api/3/issue/{issueIdOrKey}` - Delete issue
- `POST /rest/api/3/issue/{issueIdOrKey}/comment` - Add comment

**Searching & Filtering**
- `GET /rest/api/3/search` - Search issues with JQL
- `POST /rest/api/3/issues/search` - Search (alternative POST method)

**Projects**
- `GET /rest/api/3/project` - List projects
- `GET /rest/api/3/project/{projectIdOrKey}` - Get project details

**Users**
- `GET /rest/api/3/users/search` - Search users
- `GET /rest/api/3/user?accountId={id}` - Get user details
- `GET /rest/api/3/myself` - Get current user

**Workflows & Transitions**
- `GET /rest/api/3/issue/{issueIdOrKey}/transitions` - Get available transitions
- `POST /rest/api/3/issue/{issueIdOrKey}/transitions` - Transition issue

**Custom Fields**
- `GET /rest/api/3/field` - List all fields (including custom)
- `GET /rest/api/3/field/search` - Search for fields

**Webhooks**
- `GET /rest/api/3/webhook` - List webhooks
- `POST /rest/api/3/webhook` - Create webhook
- `DELETE /rest/api/3/webhook/{id}` - Delete webhook

### Step 4: Request Formats and Parameters

#### Search with JQL (JQL Query Language)

Most powerful way to query issues:

```bash
GET /rest/api/3/search?jql=project=PROJ AND status="In Progress"&maxResults=50
```

**JQL Examples**:
```
# Recent issues
project = PROJ AND created >= -7d

# Assigned to me
assignee = currentUser()

# Status workflow
status in (Open, "In Progress") AND updated >= -1d

# Custom fields (need field ID)
customfield_10014 = "Epic Name"

# Text search
summary ~ "bug fix" OR description ~ "critical"

# Complex filtering
(project = PROJ OR project = OTHER)
  AND status != Done
  AND priority >= High
  AND created >= 2024-01-01
```

**JQL Functions**:
- `currentUser()` - Current authenticated user
- `endOfDay()`, `startOfDay()` - Date functions
- `now()` - Current timestamp
- `issueFunction()` - Advanced scripting

#### Query Parameters

Common parameters for `/search`:
- `jql` - JQL query string
- `startAt` - Pagination start (default 0)
- `maxResults` - Items per page (default 50, max 100)
- `fields` - Comma-separated field names to return
- `expand` - Additional data to include (changelog, transitions)
- `orderBy` - Sort order (e.g., "created DESC")

```python
# Using JiraClient
issues = client.search_issues(
    jql="project = PROJ AND status = Open",
    startAt=0,
    maxResults=100,
    expand=["changelog"]
)
```

#### Create Issue Request

Request body for POST `/rest/api/3/issues`:

```json
{
  "fields": {
    "project": {"key": "PROJ"},
    "summary": "Issue summary",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [{"type": "text", "text": "Description text"}]
        }
      ]
    },
    "issuetype": {"name": "Task"},
    "assignee": {"accountId": "user-account-id"},
    "priority": {"name": "High"},
    "labels": ["bug", "urgent"]
  }
}
```

#### Update Issue Request

PUT `/rest/api/3/issue/{issueKey}`:

```json
{
  "fields": {
    "summary": "Updated summary",
    "description": {"type": "doc", "version": 1, "content": []},
    "priority": {"name": "Medium"},
    "assignee": {"accountId": "new-user-id"}
  }
}
```

### Step 5: Expansion and Field Selection

Use `expand` parameter to include additional data:

```bash
GET /rest/api/3/issue/PROJ-123?expand=changelog,transitions
```

**Common expansions**:
- `changelog` - Issue change history (required for state duration analysis)
- `transitions` - Available workflow transitions
- `editmeta` - Metadata about what fields can be edited
- `names` - Human-readable field names

**Field Selection** - Return only needed fields:
```bash
GET /rest/api/3/search?fields=key,summary,status,assignee&maxResults=100
```

### Step 6: Pagination

For large result sets, use pagination:

```python
start_at = 0
max_results = 50
all_issues = []

while True:
    issues = client.search_issues(
        jql="project = PROJ",
        startAt=start_at,
        maxResults=max_results
    )
    all_issues.extend(issues)

    if len(issues) < max_results:
        break
    start_at += max_results
```

Response includes pagination metadata:
```json
{
  "startAt": 0,
  "maxResults": 50,
  "total": 523,
  "isLast": false,
  "values": [...]
}
```

### Step 7: Atlassian Document Format (ADF)

Rich text content (descriptions, comments) uses ADF. The project's `JiraDocumentBuilder` simplifies this:

```python
from jira_tool.formatter import JiraDocumentBuilder

doc = JiraDocumentBuilder()
doc.add_heading("Title", level=1)
doc.add_paragraph(doc.bold("Key"), doc.add_text(": "), doc.add_text("Value"))
doc.add_bullet_list(["Item 1", "Item 2"])
doc.add_code_block("code content", language="python")
adf = doc.build()  # Returns ADF dict for API
```

**ADF Structure**:
```json
{
  "type": "doc",
  "version": 1,
  "content": [
    {
      "type": "heading",
      "attrs": {"level": 1},
      "content": [{"type": "text", "text": "Heading"}]
    },
    {
      "type": "paragraph",
      "content": [{"type": "text", "text": "Paragraph"}]
    }
  ]
}
```

**Common ADF nodes**:
- `heading` - Headings (levels 1-6)
- `paragraph` - Text paragraphs
- `bulletList` / `orderedList` - Lists
- `codeBlock` - Code blocks
- `panel` - Info panels (info, note, warning, success, error)
- `blockquote` - Block quotes
- `table` - Tables

See references/reference.md for comprehensive ADF examples.

### Step 8: Error Handling and Status Codes

Common HTTP status codes: