jira-api

Jira REST API

Jira Cloud 플랫폼의 REST API는 애플리케이션을 빌드하거나, Jira와 상호작용을 스크립팅하거나, 다른 형태의 통합을 개발할 때 Jira를 프로그래밍 방식으로 다룰 수 있게 해 줘요. 이 문서는 Jira Cloud에서 사용할 수 있는 REST 리소스와 HTTP 응답 코드, 요청·응답 예시를 정리한 공식 문서예요. REST API v3는 현재 최신 버전이고, v2와 v3는 같은 연산(operations) 집합을 제공하지만 v3는 Atlassian Document Format(ADF)을 지원한다는 차이가 있어요. 이슈·댓글·워크로그 등을 다룰 때 ADF 형식을 쓸 수 있으니 참고하면 좋아요.

출처: 문서

본문

API 개요 (About)

Jira REST API를 사용하면 이슈 생성·조회·수정, 프로젝트·사용자 관리, Agile(Jira Software) 보드와 스프린트, 워크플로우, 권한, 스크린 등 Jira가 제공하는 거의 모든 리소스를 프로그램으로 제어할 수 있어요. 문서에 나오는 주요 리소스 카테고리는 다음과 같아요.

Issues: 이슈 CRUD, 검색(JQL), 댓글, 워크로그, 첨부파일, 링크, 우선순위, 감시자 등
Agile · Plans: 보드·스프린트·에픽 등 Jira Software(Agile) 리소스
Projects: 프로젝트, 컴포넌트, 버전, 역할, 타입, 역할 담당자 등
Users · Groups: 사용자 검색, 프로필, 그룹, 사용자 속성 등
그 밖에 워크플로우, 필드·스크린·필드 스킴, 웹훅, 감사 기록, 대시보드 등

모든 REST API 호출 URI는 일반적으로 /rest/api/3/<resource-name> 구조를 가져요. 예를 들어 특정 이슈는 이렇게 조회해요.

GET https://your-domain.atlassian.net/rest/api/3/issue/DEMO-1

인증 (Authentication)

인증 방식은 통합 형태에 따라 달라져요.

Forge 앱: Forge 앱은 REST API 스코프(REST API scopes)로 인증해요. URI 구조는 /rest/api/3/<resource-name>예요.
Connect 앱: Connect 라이브러리에 JWT 기반 인증이 내장되어 있고, 스코프 또는 사용자 대행(impersonation)으로 권한을 구현해요. URI 구조는 https://<site-url>/rest/api/3/<resource-name>이에요.
OAuth 2.0 (3LO): Forge·Connect가 아닌 일반 통합은 승인 코드 그랜트(authorization code grant, 3LO)를 사용해요. URI 구조는 https://api.atlassian.com/ex/jira/<cloudId>/rest/api/3/<resource-name>이에요.
기본 인증 (Basic auth): 개인 스크립트·봇·임시 실행에는 basic authentication을 사용할 수 있어요. URI 구조는 https://<site-url>/rest/api/3/<resource-name>이에요.

기본 인증을 쓰는 임시 호출 예시는 다음과 같아요.

curl --user [email protected]:YOUR_API_TOKEN \
  'https://your-domain.atlassian.net/rest/api/3/issue/10010'

스크립트나 봇을 만들 때는 개인 액세스 토큰(API token)을 만들어 basic auth의 비밀번호로 사용하는 걸 권장해요. 인증과 보안에 대한 자세한 내용은 공식 문서의 Basic auth for REST APIs와 OAuth 2.0 (3LO) apps를 참고해요.

이슈 CRUD (Issue)

이슈를 만들고·조회하고·수정하고·삭제하는 핵심 연산은 다음과 같아요. 세부 스키마는 각 리소스 문서(/rest/api/3/issue 등)에서 확인할 수 있어요.

이슈 생성: POST /rest/api/3/issue
이슈 조회: GET /rest/api/3/issue/{issueIdOrKey}
이슈 수정: PUT /rest/api/3/issue/{issueIdOrKey}
이슈 삭제: DELETE /rest/api/3/issue/{issueIdOrKey}
이슈 검색 (JQL): POST /rest/api/3/search

이슈를 생성하는 요청 예시예요.

curl --request POST \
  --url 'https://your-domain.atlassian.net/rest/api/3/issue' \
  --user '[email protected]:YOUR_API_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "fields": {
      "project": { "key": "DEMO" },
      "summary": "첫 번째 이슈",
      "issuetype": { "name": "Task" }
    }
  }'

요청에 인증·스코프 외에도 해당 연산이 요구하는 권한(operation permission)이 있어야 해요. 대부분의 연산은 호출 사용자가 필요한 권한을 가지고 있어야 동작해요.

권한 (Operation permissions)

대부분의 연산은 권한을 요구해요. 권한은 그룹·프로젝트 역할·이슈 역할에 부여하거나 사용자에게 직접 부여할 수 있어요. 자주 쓰이는 권한은 다음과 같아요.

Administer the Cloud site: site-admins 그룹의 사용자가 가져요.
Administer Jira: Jira Administrators 전역 권한으로 부여돼요.
Administer a project in Jira: 프로젝트의 Administer projects 권한으로 부여돼요.
Access a project in Jira: 프로젝트의 Browse projects 권한으로 부여돼요.
Access Jira: Jira Users 전역 권한으로 부여돼요.

일부 연산은 익명 접근(anonymous access)을 지원하지만, 기본적으로 Jira REST API는 익명 접근을 켜두지 않아요. 익명으로 접근 가능한 연산은 문서에 "This operation can be accessed anonymously."라고 표시돼 있어요.

확장·페이지네이션·정렬 (Expansion, Pagination, Ordering)

응답의 일부 리소스는 요청에서 지정하지 않으면 기본적으로 반환되지 않아요. expand 쿼리 파라미터로 확장하면 응답을 단순화하고 네트워크 트래픽을 최소화할 수 있어요. 중첩은 . 점 표기, 여러 개는 쉼표로 구분해요.

GET issue/JRACLOUD-34423?expand=names,renderedFields

대량 컬렉션을 반환할 수 있는 연산은 페이지네이션을 적용해요. 응답은 페이지 메타데이터가 있는 JSON 객체로 감싸져요.

{
    "startAt" : 0,
    "maxResults" : 10,
    "total": 200,
    "isLast": false,
    "values": [
        { "result": 0 },
        { "result": 1 },
        { "result": 2 }
    ]
}

startAt은 해당 페이지에서 첫 번째 항목의 인덱스예요.
maxResults는 한 페이지가 반환할 수 있는 최대 항목 수예요.
total은 전체 페이지에 담긴 총 항목 수인데, 후속 페이지를 요청하면서 바뀔 수 있어요.
isLast는 반환된 페이지가 마지막인지 여부예요.

일부 연산은 orderby 쿼리 파라미터로 정렬을 지원해요. 기본은 오름차순이고, +(오름차순) 또는 -(내림차순) 기호로 바꿀 수 있어요.

?orderBy=name    # name 필드 오름차순
?orderBy=-name   # name 필드 내림차순

Rate limit (비율 제한)

Jira Cloud REST API에는 과도한 트래픽을 막기 위한 요청 빈도 제한(rate limiting)이 적용돼요. 부하가 높은 스크립트나 봇을 만들 때는 응답을 수집하는 사이에 잠시 대기하는 것이 좋고, 429(Too Many Requests) 같은 상태 코드에 대한 처리를 넣어두는 게 좋아요. 세부 기준은 공식 문서의 Rate limiting 페이지에서 확인할 수 있어요.

타임스탬프·헤더·상태 코드 (Timestamps, Headers, Status codes)

타임스탬프: 최상위 타임스탬프(예: updated, created)는 기본적으로 ISO 8601 형식, 시스템 기본 사용자 시간대 기준으로 반환돼요. 로그인 사용자의 시간대로 받으려면 expand의 renderedFields를 참고해요.
특수 헤더: multipart/form-data를 받는 연산은 CSRF(XSRF) 보호 때문에 X-Atlassian-Token: no-check 헤더를 요구해요. 응답의 X-AAccountId 헤더에는 인증된 사용자의 Atlassian 계정 ID가 담겨요.
상태 코드: 표준 HTTP 상태 코드를 사용해요. 오류 상태 코드를 반환하는 연산은 오류 상세를 담은 응답 본문(errorMessages, errors, status)을 함께 반환할 수 있어요.
비동기 연산: 오래 걸리거나 비싼 연산은 비동기 태스크로 예약하고 303 (See Other) 응답과 Location 헤더로 대기열 태스크 위치를 알려줘요. 태스크가 끝나면 응답 객체에 result 필드가 생겨요. 태스크는 실행 순서가 보장되지 않으니, 순서가 중요하면 이전 태스크가 끝난 뒤에 다음을 시작해야 해요.

더 알아보기 (Learn more)

공식 문서