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) 코드 등에 직접 노출되지 않도록 서버 측에서 안전하게 관리해야 합니다.

📡 공통 응답 포맷 (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를 기본으로 합니다.

버전: 1.2 최종 업데이트: 2026-04-09 마크다운 원본: giipv3/public/help/api-reference.ko.md