DataGSM OpenAPI SDK for JavaScript / TypeScript

개요

DataGSM OpenAPI SDK for JavaScript는 DataGSM API를 Node.js 및 브라우저 환경에서 쉽고 안전하게 사용할 수 있도록 설계된 공식 클라이언트 SDK입니다.

이 SDK는 모든 API 요청에 대해 최신 TypeScript 타입을 지원하며, Promise 기반의 비동기 인터페이스를 통해 학생, 동아리, 프로젝트, NEIS(급식, 학사일정, 시간표) 데이터에 효율적으로 접근할 수 있게 해줍니다.

주요 특징

특징	설명
강력한 타입 지원	TypeScript를 기본으로 지원하여 자동 완성 및 컴파일 타임 에러 검출이 가능합니다.
비동기 API	`async/await` 및 `Promise`를 기반으로 한 직관적인 비동기 프로그래밍을 지원합니다.
세밀한 에러 핸들링	HTTP 상태 코드별 전용 에러 클래스를 제공하여 예외 처리가 명확합니다.
유연한 설정	타임아웃, 커스텀 헤더, Base URL 등을 자유롭게 변경할 수 있습니다.
경량 설계	외부 의존성을 최소화하고 표준 `fetch` API를 사용하여 가볍고 빠릅니다.

시스템 요구사항

항목	최소 버전	권장 버전
Node.js	20.x 이상	22.x 이상
TypeScript	5.0 이상	최신 버전

설치

프로젝트에서 사용하는 패키지 매니저에 맞춰 설치하세요.

npm install @themoment-team/datagsm-openapi

pnpm add @themoment-team/datagsm-openapi

yarn add @themoment-team/datagsm-openapi

빠른 시작

1. 클라이언트 초기화

먼저 DataGsmClient 인스턴스를 생성합니다. API 키는 필수 파라미터입니다.

import { DataGsmClient } from '@themoment-team/datagsm-openapi';

// 기본 설정으로 클라이언트 생성
const client = new DataGsmClient({
  apiKey: 'your-api-key-here',
});

// 상세 설정 포함 (선택사항)
const advancedClient = new DataGsmClient({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://example.com', // 커스텀 URL (기본값: https://openapi.datagsm.kr)
  timeout: 5000, // 5초 타임아웃 (기본값: 30초)
});

2. API 호출 예제

학생 데이터 조회

// 학생 목록 조회 (1학년 1반)
const response = await client.students().getStudents({
  grade: 1,
  classNum: 1,
  size: 50
});

// 결과 처리
response.data.students.forEach((student) => {
  console.log(`${student.name} - ${student.email}`);
});

// 학생 목록 조회 (1학년 1반)
const response = await client.students().getStudents({
  grade: 1,
  classNum: 1,
  size: 50
});

// 결과 처리
response.data.students.forEach((student: Student) => {
  console.log(`${student.name} - ${student.email}`);
});

급식 데이터 조회

// 특정 날짜의 급식 조회
const response = await client.neis().getMeals({
  date: '2026-02-04' // YYYY-MM-DD 포맷
});

// 급식 데이터 출력
response.data.meals.forEach((meal) => {
  console.log(`${meal.mealType}`);
  meal.mealMenu.forEach(menu => console.log(`- ${menu}`));
});

// 특정 날짜의 급식 조회
const response = await client.neis().getMeals({
  date: '2026-02-04' // YYYY-MM-DD 포맷
});

// 급식 데이터 출력
response.data.meals.forEach((meal: Meal) => {
  console.log(`${meal.mealType}`);
  meal.mealMenu.forEach(menu => console.log(`- ${menu}`));
});

API 레퍼런스

학생 API

client.students() - 학생 데이터 조회

메서드	설명	반환 타입
`getStudents(request)`	조건에 맞는 학생 목록 조회	`Promise<GetStudentsResponse>`

요청 파라미터

파라미터	타입	설명
`studentId`	`number`	학생 ID
`name`	`string`	이름
`email`	`string`	이메일
`grade`	`number`	학년
`classNum`	`number`	반
`number`	`number`	번호
`sex`	`'MAN' \| 'WOMAN'`	성별
`role`	`Role`	학생 역할
`dormitoryRoom`	`number`	기숙사 호실
`specialty`	`string`	특기 분야
`major`	`Major`	전공
`githubId`	`string`	GitHub ID
`includeGraduates`	`boolean`	졸업생 포함 여부
`includeWithdrawn`	`boolean`	자퇴생 포함 여부
`onlyEnrolled`	`boolean`	재학생만 조회
`page`	`number`	페이지 번호
`size`	`number`	페이지 크기
`sortBy`	`StudentSortBy`	정렬 기준
`sortDirection`	`'ASC' \| 'DESC'`	정렬 방향

const students = await client.students().getStudents({
  grade: 1,
  page: 0,
  size: 20,
});

동아리 API

client.clubs() - 동아리 데이터 조회

메서드	설명	반환 타입
`getClubs(request)`	조건에 맞는 동아리 목록 조회	`Promise<GetClubsResponse>`

요청 파라미터

파라미터	타입	설명
`clubId`	`number`	동아리 ID
`clubName`	`string`	동아리 이름
`clubType`	`'MAJOR_CLUB' \| 'AUTONOMOUS_CLUB'`	동아리 유형
`clubStatus`	`'ACTIVE' \| 'ABOLISHED'`	동아리 상태
`foundedYear`	`number`	설립 연도
`page`	`number`	페이지 번호
`size`	`number`	페이지 크기
`includeLeaderInParticipants`	`boolean`	참여자 목록에 부장 포함
`sortBy`	`ClubSortBy`	정렬 기준
`sortDirection`	`'ASC' \| 'DESC'`	정렬 방향

const clubs = await client.clubs().getClubs({
  clubType: 'MAJOR_CLUB',
});

프로젝트 API

client.projects() - 프로젝트 데이터 조회

메서드	설명	반환 타입
`getProjects(request)`	조건에 맞는 프로젝트 목록 조회	`Promise<GetProjectsResponse>`

요청 파라미터

파라미터	타입	설명
`projectId`	`number`	프로젝트 ID
`projectName`	`string`	프로젝트 이름
`clubId`	`number`	동아리 ID
`status`	`'ACTIVE' \| 'ENDED'`	프로젝트 상태
`page`	`number`	페이지 번호
`size`	`number`	페이지 크기
`sortBy`	`ProjectSortBy`	정렬 기준
`sortDirection`	`'ASC' \| 'DESC'`	정렬 방향

const projects = await client.projects().getProjects({
  projectName: 'DataGSM',
});

NEIS API

client.neis() - 나이스 교육정보시스템 데이터 조회

메서드	설명	반환 타입
`getMeals(request)`	급식 데이터 조회	`Promise<GetMealsResponse>`
`getSchedules(request)`	학사일정 조회	`Promise<GetSchedulesResponse>`
`getTimetables(request)`	시간표 데이터 조회	`Promise<GetTimetablesResponse>`

요청 파라미터

메서드	파라미터	타입	설명
`getMeals`	`date`	`string`	조회 날짜
`getMeals`	`fromDate`	`string`	조회 시작 날짜
`getMeals`	`toDate`	`string`	조회 종료 날짜
`getMeals`	`isValidDateCombination`	`boolean`	날짜 조합 검증 여부
`getMeals`	`isValidDateRange`	`boolean`	날짜 범위 검증 여부
`getMeals`	`isValidDateRangePeriod`	`boolean`	날짜 범위 기간 검증 여부
`getSchedules`	`date`	`string`	조회 날짜
`getSchedules`	`fromDate`	`string`	조회 시작 날짜
`getSchedules`	`toDate`	`string`	조회 종료 날짜
`getSchedules`	`isValidDateCombination`	`boolean`	날짜 조합 검증 여부
`getSchedules`	`isValidDateRange`	`boolean`	날짜 범위 검증 여부
`getSchedules`	`isValidDateRangePeriod`	`boolean`	날짜 범위 기간 검증 여부
`getTimetables`	`grade`	`number`	학년
`getTimetables`	`classNum`	`number`	반
`getTimetables`	`date`	`string`	조회 날짜
`getTimetables`	`fromDate`	`string`	조회 시작 날짜
`getTimetables`	`toDate`	`string`	조회 종료 날짜
`getTimetables`	`isValidDateCombination`	`boolean`	날짜 조합 검증 여부
`getTimetables`	`isValidDateRange`	`boolean`	날짜 범위 검증 여부
`getTimetables`	`isValidDateRangePeriod`	`boolean`	날짜 범위 기간 검증 여부
`getTimetables`	`isDateRequired`	`boolean`	날짜 필수 여부 검증

// 학사일정 조회
const schedules = await client.neis().getSchedules({
  fromDate: '2026-03-01',
  toDate: '2026-03-31',
});

// 시간표 조회
const timetables = await client.neis().getTimetables({
  grade: 2,
  classNum: 3,
  date: '2026-03-01',
});

예외 처리

SDK는 발생한 오류 상황에 맞는 전용 에러 클래스를 제공합니다.

에러 클래스 종류

에러 클래스	HTTP 상태	상황
`BadRequestError`	400	잘못된 요청 파라미터
`UnauthorizedError`	401	유효하지 않은 API 키
`ForbiddenError`	403	요청 권한 범위 부족
`NotFoundError`	404	리소스를 찾을 수 없음
`RateLimitError`	429	요청 횟수 제한 초과
`ServerError`	500+	서버 내부 오류
`NetworkError`	-	네트워크 연결 실패 또는 타임아웃

예외 처리 예제

import { DataGsmError, RateLimitError, UnauthorizedError } from '@themoment-team/datagsm-openapi';

try {
  const response = await client.students().getStudents();
} catch (error) {
  if (error instanceof UnauthorizedError) {
    console.error('API 키를 확인해주세요.');
  } else if (error instanceof RateLimitError) {
    console.error('너무 많은 요청을 보냈습니다. 잠시 후 시도해주세요.');
    console.log(`재시도 가능 시간: ${error.retryAfter}초 후`);
  } else if (error instanceof DataGsmError) {
    console.error(`API 에러 발생 (${error.statusCode}): ${error.message}`);
  } else {
    console.error('알 수 없는 오류가 발생했습니다.', error);
  }
}

보안 가이드

API 키 관리

API 키는 절대 클라이언트 측 JavaScript(브라우저) 코드에 직접 노출하지 마세요. 환경 변수를 사용하여 안전하게 관리하고 서버 측에서 사용하시기를 권장합니다.

환경 변수 사용 예시 (`.env`)

DATAGSM_API_KEY=your_secret_api_key

const client = new DataGsmClient({
  apiKey: process.env.DATAGSM_API_KEY,
});

문제 해결

자주 발생하는 문제

401 Unauthorized 오류

원인: API 키가 유효하지 않거나 만료됨

해결 방법:

API 키가 올바르게 설정되었는지 확인
API 키가 만료되지 않았는지 확인
필요시 새로운 API 키 발급

403 Forbidden 오류

원인: 요청한 API에 대한 권한 범위 부족

해결 방법:

API 키의 권한 범위 확인
필요한 권한 범위가 부여되었는지 확인
권한 범위 추가가 필요한 경우 관리자에게 문의

타임아웃 오류

원인: 네트워크 연결 불안정 또는 서버 응답 지연

해결 방법:

네트워크 상태 확인
타임아웃 설정을 늘려 재시도 (기본값은 30초)
서버 상태 확인

추가 리소스

GitHub 저장소: DataGSM OpenAPI SDK JavaScript ↗
이슈 트래커: GitHub Issues ↗

문의사항이나 버그 리포트는 GitHub Issues를 통해 제출해 주세요.

DataGSM OpenAPI SDK for JavaScript / TypeScript

개요

주요 특징

시스템 요구사항

설치

빠른 시작

1. 클라이언트 초기화

2. API 호출 예제

학생 데이터 조회

급식 데이터 조회

API 레퍼런스

학생 API

요청 파라미터

동아리 API

요청 파라미터

프로젝트 API

요청 파라미터

NEIS API

요청 파라미터

예외 처리

에러 클래스 종류

예외 처리 예제

보안 가이드

API 키 관리

환경 변수 사용 예시 (.env)

문제 해결

자주 발생하는 문제

401 Unauthorized 오류

403 Forbidden 오류

타임아웃 오류

추가 리소스

환경 변수 사용 예시 (`.env`)