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-openapipnpm add @themoment-team/datagsm-openapiyarn 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.data.hellogsm.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.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.forEach((meal: Meal) => {
console.log(`${meal.mealType}`);
meal.mealMenu.forEach(menu => console.log(`- ${menu}`));
});API 레퍼런스
학생 API
client.students() - 학생 데이터 조회
| 메서드 | 설명 | 반환 타입 |
|---|---|---|
getStudents(request) | 조건에 맞는 학생 목록 조회 | Promise<GetStudentsResponse> |
const students = await client.students().getStudents({
grade: 1,
page: 0,
size: 20,
});동아리 API
client.clubs() - 동아리 데이터 조회
| 메서드 | 설명 | 반환 타입 |
|---|---|---|
getClubs(request) | 조건에 맞는 동아리 목록 조회 | Promise<GetClubsResponse> |
const clubs = await client.clubs().getClubs({
clubType: 'MAJOR_CLUB',
});프로젝트 API
client.projects() - 프로젝트 데이터 조회
| 메서드 | 설명 | 반환 타입 |
|---|---|---|
getProjects(request) | 조건에 맞는 프로젝트 목록 조회 | Promise<GetProjectsResponse> |
const projects = await client.projects().getProjects({
projectName: 'DataGSM',
});NEIS API
client.neis() - 나이스 교육정보시스템 데이터 조회
| 메서드 | 설명 | 반환 타입 |
|---|---|---|
getMeals(request) | 급식 데이터 조회 | Promise<GetMealsResponse> |
getSchedules(request) | 학사일정 조회 | Promise<GetSchedulesResponse> |
// 학사일정 조회
const schedules = await client.neis().getSchedules({
fromDate: '2026-03-01',
toDate: '2026-03-31',
});예외 처리
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_keyconst 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를 통해 제출해 주세요.