Jira API 호출 후 반환되는 값의 구조 이해하기

Python

Jira

Author

gabriel yang

Published

October 6, 2024

Jira API 호출 후 리턴값 구조 이해하기: 가이드

Jira는 이슈 추적과 프로젝트 관리에 널리 사용되는 강력한 도구입니다. Jira의 REST API를 사용할 때, API가 반환하는 응답 데이터를 이해하는 것은 정보를 효율적으로 가져오고 처리하는 데 중요한 역할을 합니다. 이 글에서는 Jira API 호출 후 반환되는 JSON 응답 구조를 설명하고, 자주 사용되는 요소들을 알아보겠습니다.

1. Jira REST API 개요

Jira REST API를 통해 프로그래밍적으로 Jira와 상호작용할 수 있습니다. 이슈, 프로젝트, 사용자, 사용자 정의 필드 등에 대한 정보를 가져오거나 조작할 수 있으며, API는 그에 대한 자세한 JSON 응답을 제공합니다. 예를 들어, 특정 이슈 정보를 가져오기 위한 API 요청은 아래와 같은 형식입니다.

curl -D- -u username:password -X GET -H "Content-Type: application/json" "https://your-domain.atlassian.net/rest/api/3/issue/ISSUE-KEY"

이 API 호출에 대한 응답은 요청된 이슈에 대한 데이터를 포함하는 JSON 구조로 반환됩니다. 이제 리턴되는 주요 구성 요소를 살펴보겠습니다.

2. Jira API 응답의 기본 구조

Jira API의 일반적인 응답은 다음과 같은 상위 레벨 필드를 가진 JSON 객체입니다:

{
  "expand": "renderedFields,names,schema,transitions,operations,editmeta,changelog",
  "id": "10000",
  "self": "https://your-domain.atlassian.net/rest/api/3/issue/10000",
  "key": "ISSUE-1",
  "fields": { ... }
}

주요 필드:

expand: 이 리소스에서 추가로 확장할 수 있는 필드 또는 섹션을 나타내는 문자열입니다.
id: 이슈의 고유한 내부 식별자입니다.
self: 이슈에 대한 API 요청 URL로, 후속 요청을 위한 참조로 사용할 수 있습니다.
key: 이슈의 읽기 쉬운 키 값(예: “PROJ-123”)입니다.
fields: 이곳에 실제 데이터가 포함됩니다. fields 객체는 이슈의 요약, 설명, 상태 등 이슈에 대한 모든 정보를 담고 있습니다.

3. Fields 객체 이해하기

fields 객체에는 이슈에 대한 상세 정보가 들어있습니다. 이 객체는 다양한 속성을 나타내는 여러 키-값 쌍으로 구성됩니다.

다음은 fields 객체의 예시입니다:

{
  "summary": "Issue Summary",
  "description": "Detailed issue description",
  "status": {
    "self": "https://your-domain.atlassian.net/rest/api/3/status/1",
    "description": "The issue is open and ready for work.",
    "name": "To Do",
    "id": "1",
    "statusCategory": {
      "self": "https://your-domain.atlassian.net/rest/api/3/statuscategory/1",
      "id": 1,
      "key": "new",
      "colorName": "blue-gray",
      "name": "To Do"
    }
  },
  "assignee": {
    "self": "https://your-domain.atlassian.net/rest/api/3/user?username=user",
    "name": "user",
    "emailAddress": "user@example.com",
    "avatarUrls": {
      "48x48": "https://your-domain.atlassian.net/secure/useravatar?size=small&ownerId=user"
    },
    "displayName": "John Doe",
    "active": true
  },
  "priority": {
    "self": "https://your-domain.atlassian.net/rest/api/3/priority/1",
    "name": "Highest",
    "id": "1"
  },
  ...
}

주요 필드 설명:

summary: 이슈의 간단한 요약입니다.
description: 이슈의 상세 설명입니다.
status: 이슈의 현재 상태에 대한 정보를 담은 객체로, 상태 이름, 설명, 상태 카테고리 등이 포함됩니다.
assignee: 현재 이슈에 할당된 사용자에 대한 정보로, 이름, 이메일 주소, 아바타 URL 등이 포함됩니다.
priority: 이슈의 우선순위 정보를 나타내는 객체입니다 (예: “Highest”).

이와 같이 fields 객체는 여러 중첩된 객체 또는 단순한 값을 포함할 수 있습니다.

4. 중첩 객체 및 리스트

일부 필드는 status나 assignee와 같은 객체를 포함하고 있으며, 이러한 중첩된 객체는 이슈에 대한 더 세부적인 정보를 제공합니다. 또한 일부 필드는 배열 형태로 데이터를 반환할 수 있습니다.

예를 들어, comments 필드는 다음과 같이 댓글 객체 리스트를 반환할 수 있습니다:

"comment": {
  "comments": [
    {
      "self": "https://your-domain.atlassian.net/rest/api/3/comment/10000",
      "id": "10000",
      "author": {
        "self": "https://your-domain.atlassian.net/rest/api/3/user?username=user",
        "name": "user",
        "displayName": "John Doe"
      },
      "body": "This is a comment",
      "created": "2024-01-01T12:00:00.000+0000"
    }
  ],
  "maxResults": 1,
  "total": 1,
  "startAt": 0
}

여기서 comments 필드는 댓글 객체의 배열을 나타내며, 각 댓글은 고유한 메타데이터를 가지고 있습니다.

5. 사용자 정의 필드 (Custom Fields)

Jira에서 사용자 정의 필드는 Jira 인스턴스에 따라 다르며, 이러한 필드는 fields 객체에 포함되어 있으며 고유 식별자와 함께 반환됩니다.

예시:

"customfield_10000": "사용자 정의 필드 값"

여기서 customfield_10000은 특정 사용자 정의 필드를 나타내며, 이 필드의 의미는 Jira 관리자나 관련 문서를 통해 확인해야 합니다.

6. 페이징 처리된 응답

여러 결과를 반환하는 요청(예: 이슈 리스트)의 경우, Jira API는 큰 데이터 세트를 관리하기 위해 페이징 처리를 사용합니다. 이 경우 응답은 다음과 같은 페이징 메타데이터와 함께 반환됩니다:

{
  "startAt": 0,
  "maxResults": 50,
  "total": 100,
  "issues": [
    { "id": "10000", "key": "ISSUE-1", "fields": { ... } },
    { "id": "10001", "key": "ISSUE-2", "fields": { ... } },
    ...
  ]
}

startAt: 이 응답에서 반환된 첫 번째 항목의 인덱스입니다.
maxResults: 응답에서 반환된 최대 항목 수입니다 (보통 API 요청에서 정의됨).
total: 요청에 일치하는 총 항목 수입니다.
issues: 이슈 객체 배열로, 각각은 우리가 앞서 설명한 fields와 유사한 구조를 가집니다.

Note

페이징(Pagination)은 API 응답에서 한 번에 많은 데이터를 처리하지 않고, 데이터를 여러 페이지로 나누어 전달하는 방식입니다. Confluence REST API에서도 페이징 처리를 통해 대량의 데이터(예: 댓글, 페이지 등)를 일정한 크기씩 나눠서 가져올 수 있습니다.

7. 에러 응답

API 요청이 실패한 경우, Jira API는 다음과 같은 에러 메시지를 반환합니다:

{
  "errorMessages": ["Issue does not exist"],
  "errors": {}
}

errorMessages: 사람이 읽을 수 있는 오류 메시지 목록입니다.
errors: 필드별 오류가 발생한 경우, 해당 오류가 여기에 표시될 수 있습니다.