CatQuest 데이터 API 레퍼런스
CatQuest 화면은 **giip 이슈 목록 API(giipIssues)**를 읽어 각 이슈를 고양이 카드로 그립니다. 이 문서는 그 데이터 원천을 API로 직접 조회하는 방법과, 화면의 상태→고양이 매핑을 설명합니다.
- 호스트:
https://giipfaw.azurewebsites.net - 인증:
x-api-key헤더(또는Authorization: Bearer <key>)에 로그인 사용자의 AK, 프로젝트 SK, 또는 사용자 고정 키 중 하나를 전달합니다. 세 종류의 상세 정의·발급처·권한 범위는 이슈·태스크 API → 인증 (이 API와 동일한giipIssues엔드포인트를 사용하므로 인증 사양도 공통)을 참조하세요. 조회 범위는 키의csn(프로젝트) 로 제한됩니다. JSON 바디나 쿼리 문자열로 키를 전달하는 방식은 지원되지 않습니다(실측 확인, 2026-08-20) — 반드시 헤더로 전달하세요. - 응답 코드(RstVal) 규약은 API 결과 코드 를 참조하세요.
이슈 목록 조회 — giipIssues GET
CatQuest가 페이지 로드 시 호출하는 읽기 API입니다.
curl "https://giipfaw.azurewebsites.net/api/giipIssues?csn=47" \
-H "x-api-key: ${GIIP_API_KEY}"요청 파라미터
| 이름 | 위치 | 필수 | 설명 |
|---|---|---|---|
csn | query | ✅ | 조회할 프로젝트 번호. CatQuest는 현재 선택된 프로젝트의 csn을 자동으로 넣습니다. |
응답 예시
{
"issues": [
{
"isn": 735,
"title": "admin/catquest 유저 가이드 생성",
"status": "READY",
"regdate": "2026-07-24T08:54:00Z",
"summary": "가이드 버튼 활성화",
"last_comment_date": "2026-07-24T09:00:00Z",
"blocked_by_isn": null,
"blocked_by_title": null
}
]
}응답 필드 (CatQuest가 사용하는 것)
| 필드 | 타입 | 화면에서의 쓰임 |
|---|---|---|
isn | number | 이슈 번호(#isn 배지). 어떤 고양이를 배정할지도 isn으로 결정됩니다. |
title | string | 카드 상단 말풍선 제목 |
status | string | 고양이 행동(애니메이션)을 결정 — 아래 매핑표 참조 |
regdate | string | 등록 일시(🐣) |
summary | string | 카드 하단 요약(있을 때만) |
last_comment_date | string | null | 최종 코멘트 일시(💬), 없으면 "코멘트 없음" |
blocked_by_isn | number | null | 대기(blocked-by) 배지 — 이 이슈를 막고 있는 점유 이슈 번호 |
blocked_by_title | string | null | 대기 배지의 툴팁(점유 이슈 제목) |
상태 → 고양이 행동 매핑
CatQuest 프론트가 status 값을 다음 규칙으로 애니메이션에 매핑합니다(서버 값이 아니라 화면 표현 규칙).
| status | 고양이 상태 | 이미지 파일 패턴 |
|---|---|---|
| PENDING | playing | /images/catquest/<cat>_playing.png |
| READY | ready | /images/catquest/<cat>_ready.png |
| IN_PROGRESS | hunting | /images/catquest/<cat>_hunting.png |
| REVIEW | delivering | /images/catquest/<cat>_delivering.png |
| DONE | playing | /images/catquest/<cat>_playing.png |
<cat>은isn % 8로 8종(mochi·sherlock·nimbus·pixel·cocoa·midnight·luna·leo) 중 하나가 고정 배정됩니다.
관련 API
- 이슈 등록·수정·상태변경: 프로그램으로 이슈를 생성/전이하려면 이슈 및 태스크 API 를 참조하세요.
- 코멘트 조회/추가: 이슈 상세 화면은
giipIssueCommentsAPI를 사용합니다.
문제 해결
| 증상 | 원인 | 해결 |
|---|---|---|
401 {"error":"Auth required"} | x-api-key 헤더 자체가 없거나, JSON 바디/쿼리 문자열 등 미지원 방식으로 키를 전달함 | x-api-key: <key> 헤더(또는 Authorization: Bearer <key>)로 전달. 실측 확인: 바디 token·쿼리 ?token=은 읽히지 않습니다 |
401 {"error":"Invalid session"} | 키 오타·만료·비활성화(SK 재발급/회전, AK 세션 만료 등) | 유효한 키로 재시도하거나 재로그인합니다. 키 조건 상세는 이슈·태스크 API 참조 |
빈 issues: [](해당 csn에 이슈가 없는 경우) | 해당 csn에 이슈가 없음 | csn 값을 확인하거나 이슈를 등록합니다 |
빈 issues: [](키에 권한이 없는 경우) | 키가 그 csn에 접근 권한이 없음(401이 아니라 빈 배열이 됨 — 실측 확인, 2026-08-20) | 해당 csn용 키를 사용하거나 관리자에게 권한 부여를 요청합니다 |
csn 없이 호출 | 필수 파라미터 누락 | ?csn=<번호> 를 반드시 포함합니다 |
버전: 1.1
최종 업데이트: 2026-08-20(테스트 대상 API: giipfaw 프로덕션)
소스 파일: giipv3/public/help/api-catquest.ko.md
v1.1 변경 이력 (2026-08-20, giip #1280): 인증 섹션을 이슈·태스크 API의 확장된 인증 정의로 링크하여 중복을 제거. curl 예제를 환경변수화. 401의 원인(키 미도달/키 무효)과 csn 권한 불일치 시 동작(401이 아니라 빈 배열)을 문제 해결 표에 추가(giip-issue-api의 실측 결과 반영).