DataGSM HTTP OpenAPI Overview

개요

DataGSM HTTP OpenAPI는 학생, 동아리, 프로젝트, NEIS 데이터를 간단한 HTTP 요청을 통해 조회할 수 있는 RESTful API입니다.

표준 HTTP 프로토콜을 사용하므로 어떤 프로그래밍 언어나 플랫폼에서도 쉽게 연동할 수 있으며, JSON 형식으로 데이터를 주고받습니다.

HTTP API 사용의 이점

기본 URL

모든 API 요청은 다음 기본 URL을 사용합니다:

https://openapi.data.hellogsm.kr

공통 응답 구조

모든 성공 응답은 다음과 같은 구조로 래핑되어 반환됩니다.

{
  "status": "OK",
  "code": 200,
  "message": "OK",
  "data": {
    // 실제 응답 데이터
  }
}

인증 방식

모든 API 요청은 HTTP 헤더에 API 키를 포함해야 합니다.

X-API-KEY: your-api-key-here

API 키는 UUID 형식이며, 30일마다 갱신이 필요합니다. 만료되거나 유효하지 않은 키를 사용할 경우 401 Unauthorized 응답을 받게 됩니다.

사용 가능한 엔드포인트

요청 예시

다음은 cURL을 사용하여 학생 데이터를 조회하는 예시입니다.

curl -X GET "https://openapi.data.hellogsm.kr/v1/students?grade=1&classNum=1" \
  -H "X-API-KEY: your-api-key-here"

오류 응답

API 요청 실패 시 다음과 같은 HTTP 상태 코드가 반환될 수 있습니다.

캐싱 전략

HTTP API를 효율적으로 사용하기 위해 적절한 캐싱 전략을 적용하는 것이 중요합니다. 자주 변경되지 않는 데이터는 클라이언트 측에서 캐싱하여 불필요한 API 호출을 줄일 수 있습니다.

ETag를 활용한 캐싱

HTTP 캐싱 헤더(ETag, Cache-Control 등)를 활용하여 데이터의 신선도를 관리할 수 있습니다.

// JavaScript에서 ETag를 활용한 조건부 요청 예시
async function fetchWithCache(url, apiKey, cachedETag) {
  const headers = {
    'X-API-KEY': apiKey,
  };

  if (cachedETag) {
    headers['If-None-Match'] = cachedETag;
  }

  const response = await fetch(url, { headers });

  if (response.status === 304) {
    return { fromCache: true };
  }

  const newETag = response.headers.get('ETag');
  const data = await response.json();

  return { data, eTag: newETag, fromCache: false };
}

Rate Limiting

모든 API 키에는 요청량 제한(Rate Limit)이 적용됩니다. 제한을 초과할 경우 429 Too Many Requests 응답이 반환됩니다.

효율적인 API 사용을 위해 다음 사항을 권장합니다:

• 배치 요청: 가능한 경우 여러 데이터를 한 번에 요청합니다.
• 캐싱 활용: 자주 사용하는 데이터는 로컬에 캐싱합니다.
• 지수 백오프: Rate Limit 초과 시 지수적으로 대기 시간을 늘려 재시도합니다.

다음 단계

각 API의 상세 사용법은 아래 기술 문서를 참고하세요:

• 학생 데이터 OpenAPI
• 동아리 데이터 OpenAPI
• 프로젝트 데이터 OpenAPI
• NEIS 데이터 OpenAPI

SDK를 사용한 더 편리한 API 호출을 원한다면 SDK 기술 문서를 참고하세요.