API 레퍼런스 개요 (v1.2)
GIIP 플랫폼의 마이크로서비스 및 데이터베이스 자원을 제어하고 모니터링하기 위한 공통 API 규격과 인증 방식을 안내합니다.
📋 개요
GIIP API는 RESTful 아키텍처 원칙을 따르며, JSON 형식을 사용하여 요청을 처리하고 응답을 반환합니다. 모든 API는 보안을 위해 HTTPS 프로토콜을 통해서만 접근 가능하며, 유효한 Access Key와 Secret Key를 사용하여야 정상적인 기능 호출이 가능합니다.
🔐 인증 (Authentication)
모든 API 요청 헤더에는 다음과 같은 인증 정보가 포함되어야 합니다.
| Header Key | Description |
|---|---|
| x-giip-ak | GIIP 관리자로부터 발급받은 Access Key |
| x-giip-sk | GIIP 관리자로부터 발급받은 Secret Key |
[!IMPORTANT] Secret Key는 외부로 유출되어서는 안 되며, 클라이언트 측 자바스크립트(JS) 코드 등에 직접 노출되지 않도록 서버 측에서 안전하게 관리해야 합니다.
AK/SK 공통 용어 정의
GIIP 전체에서 쓰이는 인증 정보는 실체 기준으로 다음 3가지로 정리할 수 있습니다(2026-08-20, 이슈·태스크 API에서의 코드 확인+라이브 실측 기준).
| 종류 | 실체(테이블/컬럼) | 발급 단위 | 권한 범위 |
|---|---|---|---|
| 프로젝트 SK | tSecretKey.SKey | 프로젝트(csn)당 | 그 csn만. 호출자 개인은 특정되지 않는 공유 키 |
| 사용자 고정 키 | tCorpUser.uSecretKey | 사용자(usn)당 | 그 사용자 본인이 속한 csn(관리자 권한이면 전체 csn) |
| 로그인 세션 AK | tUserLogin.AccToken | 로그인마다 신규 발급, 24시간 후 만료 | 로그인 사용자 본인과 동일 권한 |
⚠️ 엔드포인트마다 실제 헤더 이름·전달 방식이 다릅니다. 위 표의
x-giip-ak/x-giip-sk헤더는 여러 API 그룹에서 쓰이는 일반적인 관례이지만, 이슈 관리 API(/api/giipIssues,/api/giipIssueComments)와 CatQuest API는x-api-key헤더 하나(또는Authorization: Bearer)에 AK/SK 중 하나를 담아 전달하는 방식이며,x-giip-ak/x-giip-sk라는 개별 헤더 이름은 사용하지 않습니다(실측 확인, 2026-08-20). 실제로 호출하기 전에는 반드시 해당 API의 개별 문서(이슈·태스크 API, CatQuest 데이터 API 등)에서 헤더 이름과 전달 방식을 확인하세요. 이 페이지의 표는 "GIIP 전체 인증 정보의 종류"를 보여주는 것이며, "모든 API가 동일한 헤더 이름을 쓴다"는 뜻이 아닙니다.
📡 공통 응답 포맷 (Response Format)
GIIP의 모든 API는 일관된 응답 포맷을 제공하여 클라이언트 측의 처리를 용이하게 합니다.
{
"RstVal": 0,
"RstMsg": "Success",
"Data": { ... }
}- RstVal: 성공 여부 (0: 성공, 그 외: 에러)
- RstMsg: 성공 메시지 (에러 발생 시 상세 원인 문구 포함)
- Data: 요청에 성공했을 경우 반환되는 데이터 본문
🚀 요청 형식
모든 API 요청은 Azure Function 호출 규격을 따라 application/x-www-form-urlencoded로 POST합니다.
주요 폼 데이터
| 필드 | 설명 |
|---|---|
| text | 실행하고자 하는 명령 문자열 |
| user_id | 호출하는 사용자 ID |
| token | 세션 토큰 |
| usertoken | 실제 연동에 사용되는 세션 토큰 |
🚀 API 그룹별 가이드
분야별 상세 API 명세는 다음 개별 가이드를 참조하세요.
- 서버 관리 API: 인프라 자산 조회 및 명령 실행
- 데이터베이스 API: DB 성능 및 쿼리 통계
- 이슈 관리 API: 장애 알람 및 상태 업데이트
- 비용 분석 API: 클라우드 사용량 및 비용 예측
- 프로젝트/유저 API: 권한 및 조직 관리
- 모니터링 데이터 조회 API: 실시간 CPU/MEM/Disk 메트릭, 성능 이력, 프로세스 목록
- 네트워크 보안 정책 API: 방화벽 룰 조회, IP 허용/차단, 보안 정책 일괄 배포
- 네트워크 토폴로지(Net3D) API: 인프라 연결 데이터 수집·전송 규격 (netinv, netstat, db_connections)
- 시스템 관리 API: 원격 명령 실행, 에이전트 제어, 서버 태그 관리
- KVS(키-값 저장소) API: factor 데이터 조회 (KVSFactorLast, KVSFactorList)
- Vercel 관리 API: Vercel 설정 관리 및 배포 이력 조회
- GitHub Actions 관리 API: GitHub 저장소 연동 및 워크플로우 이력 조회
- 이메일 서버 관리 API: SMTP 서버 설정 및 테스트 발송 (관리자 전용)
- Sk3 (고성능 로깅) API: 에이전트 전송 에러 감지 및 무결성 검증을 위한 High-fidelity 로깅 브릿지
- 공통 응답 값 및 결과 코드 가이드 (RstVal): tDefRst 테이블 기반의 표준 결과 코드 안내
🛠️ 공통 오류 코드
- 401 Unauthorized: 인증 정보가 유효하지 않거나 만료된 경우
- 403 Forbidden: 해당 API를 호출할 권한이 없는 경우 (IP 기반 접근 통제 포함)
- 429 Too Many Requests: 요청 빈도 제한(Rate Limit) 초과
- 500 Internal Server Error: 서버 내부 오류 및 일시적인 장애 발생
📖 개발자 참고 사항
- 엔드포인트 호출부:
src/lib/lsvrUtils.ts - 세션 관리:
sessionStorage의user_id,token,csn,cname등 참조 - 모든 연동은 HTTPS를 기본으로 합니다.
🔧 문제 해결
| 증상 | 원인 | 해결 |
|---|---|---|
| 401 Unauthorized가 반환된다 | Access Key/Secret Key가 만료되었거나 유효하지 않음 | x-giip-ak/x-giip-sk 헤더 값을 재확인하고, 필요 시 관리자에게 키 재발급을 요청합니다 |
| 403 Forbidden이 반환된다 | 해당 API 호출 권한이 없거나 IP 기반 접근 통제에 막힘 | 계정 권한과 허용 IP 여부를 확인합니다 |
응답의 RstVal이 0이 아닌데 원인을 모르겠다 | 표준 결과 코드의 의미를 확인하지 않음 | RstMsg를 확인하고 API 결과 코드 가이드에서 해당 코드를 조회합니다 |
요청이 처리되지 않거나 text 명령이 무시된다 | 요청이 application/x-www-form-urlencoded 형식이 아니거나 text/user_id/token 필드 누락 | 폼 데이터 형식과 필수 필드를 규격에 맞게 전송합니다 |
관련 문서:
버전: 1.3 최종 업데이트: 2026-08-20 마크다운 원본: giipv3/public/help/api-reference.ko.md
v1.3 변경 이력 (2026-08-20, giip #1280): "AK/SK 공통 용어 정의" 절을 추가해 프로젝트 SK/사용자 고정 키/로그인 세션 AK 3종류를 발급 테이블 기준으로 정리. 이슈 관리 API·CatQuest API는 이 페이지의
x-giip-ak/x-giip-sk헤더 관례가 아니라x-api-key헤더 하나를 쓴다는 점을 명시하고, 실제 헤더 이름은 각 API의 개별 문서에서 확인하도록 안내(세 문서 간 불일치 해소).