학생 데이터 OpenAPI

개요

학생 데이터 OpenAPI는 학생 데이터를 간단한 HTTP 요청을 통하여 서비스에 통합할 수 있도록 돕습니다. 해당 REST API를 호출하여 기본적인 학생 데이터를 획득할 수 있습니다.

인증

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

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

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

엔드포인트

GET /v1/students

권한 범위

STUDENT_READ 권한 범위가 필요합니다.

요청 파라미터

파라미터	타입	필수 여부	설명	예시
`studentId`	`Long`	선택	학생 ID	`1`
`name`	`String`	선택	이름	`홍길동`
`email`	`String`	선택	이메일	`student@gsm.hs.kr`
`grade`	`Int`	선택	학년 (1-3)	`1`
`classNum`	`Int`	선택	반 (1-4)	`1`
`number`	`Int`	선택	번호 (1-18)	`1`
`sex`	`Sex`	선택	성별 (`MAN`, `WOMAN`)	`MAN`
`role`	`StudentRole`	선택	학생 역할 (`STUDENT_COUNCIL`, `DORMITORY_MANAGER`, `GENERAL_STUDENT`, `GRADUATE`, `WITHDRAWN`)	`GENERAL_STUDENT`
`dormitoryRoom`	`Int`	선택	기숙사 호실	`301`
`includeGraduates`	`Boolean`	선택	졸업생 포함 여부 (기본값: false)	`false`
`includeWithdrawn`	`Boolean`	선택	자퇴생 포함 여부 (기본값: false)	`false`
`onlyEnrolled`	`Boolean`	선택	재학생만 조회 여부 — `true`이면 졸업생·자퇴생 모두 제외 (기본값: false)	`false`
`page`	`Int`	선택	페이지 번호 (기본값: 0)	`0`
`size`	`Int`	선택	페이지 크기 (기본값: 300)	`300`
`sortBy`	`StudentSortBy`	선택	정렬 기준 (ID, NAME, EMAIL, STUDENT_NUMBER, GRADE, CLASS_NUM, NUMBER, MAJOR, ROLE, SEX, DORMITORY_ROOM)	`STUDENT_NUMBER`
`sortDirection`	`SortDirection`	선택	정렬 방향 (ASC, DESC) (기본값: ASC)	`ASC`

파라미터 우선순위

재학 상태 필터 파라미터 간에는 다음과 같은 우선순위가 적용됩니다.

onlyEnrolled > includeGraduates > includeWithdrawn

onlyEnrolled = true — 가장 높은 우선순위. includeGraduates·includeWithdrawn 값에 무관하게 재학생만 반환됩니다.
includeGraduates — onlyEnrolled가 false일 때 유효. false이면 졸업생을 제외합니다.
includeWithdrawn — onlyEnrolled가 false일 때 유효. false이면 자퇴생을 제외합니다.

기본값(includeGraduates=false, includeWithdrawn=false, onlyEnrolled=false)으로 호출하면 졸업생·자퇴생이 모두 제외된 재학생 목록이 반환됩니다.

응답 형식

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

필드	타입	설명	예시
`status`	`String`	HTTP 상태 메시지	`OK`
`code`	`Int`	HTTP 상태 코드	`200`
`message`	`String`	응답 메시지	`OK`
`data`	`Object`	학생 데이터 목록	-

data 객체

data 필드는 다음 필드를 포함합니다.

필드	타입	설명	예시
`totalPages`	`Int`	전체 페이지 수	`1`
`totalElements`	`Long`	전체 학생 수	`300`
`students`	`List<StudentResDto>`	학생 목록	-

학생 객체 (StudentResDto)

각 학생 객체는 다음 필드를 포함합니다.

필드	타입	설명	예시
`id`	`Long`	학생 ID	`1`
`name`	`String`	이름	`홍길동`
`sex`	`Sex`	성별 (`MAN`, `WOMAN`)	`WOMAN`
`email`	`String`	이메일	`student@gsm.hs.kr`
`grade`	`Int?`	학년 (졸업/자퇴 시 `null`)	`1`
`classNum`	`Int?`	반 (졸업/자퇴 시 `null`)	`1`
`number`	`Int?`	번호 (졸업/자퇴 시 `null`)	`1`
`studentNumber`	`Int?`	학번 (졸업/자퇴 시 `null`)	`1101`
`major`	`Major?`	전공 (졸업/자퇴 시 `null`, 값: `SW_DEVELOPMENT`, `SMART_IOT`, `AI`)	`SW_DEVELOPMENT`
`role`	`StudentRole`	학생 역할 (`STUDENT_COUNCIL`, `DORMITORY_MANAGER`, `GENERAL_STUDENT`, `GRADUATE`, `WITHDRAWN`)	`GENERAL_STUDENT`
`dormitoryFloor`	`Int?`	기숙사 층 (비기숙사생인 경우 `null`)	`3`
`dormitoryRoom`	`Int?`	기숙사 호실 (비기숙사생인 경우 `null`)	`301`
`majorClub`	`ClubSummaryDto?`	전공 동아리 (미소속인 경우 `null`)	-
`autonomousClub`	`ClubSummaryDto?`	자율 동아리 (미소속인 경우 `null`)	-

동아리 객체 (ClubSummaryDto)

학생 응답에 포함된 동아리 데이터는 다음 필드를 포함합니다.

필드	타입	설명	예시
`id`	`Long`	동아리 ID	`1`
`name`	`String`	동아리 이름	`SW개발동아리`
`type`	`ClubType`	동아리 종류(`MAJOR_CLUB`, `AUTONOMOUS_CLUB`)	`MAJOR_CLUB`

요청 예시

curl -X GET "https://api.datagsm.com/v1/students?grade=1&classNum=1&page=0&size=50" \
  -H "X-API-KEY: your-api-key-here"

정렬을 포함한 요청 예시

# 학번 순으로 정렬
curl -X GET "https://api.datagsm.com/v1/students?sortBy=STUDENT_NUMBER&sortDirection=ASC&page=0&size=50" \
  -H "X-API-KEY: your-api-key-here"

# 이름 역순으로 정렬
curl -X GET "https://api.datagsm.com/v1/students?sortBy=NAME&sortDirection=DESC&page=0&size=50" \
  -H "X-API-KEY: your-api-key-here"

응답 예시

{
  "status": "OK",
  "code": 200,
  "message": "OK",
  "data": {
    "totalPages": 1,
    "totalElements": 1,
    "students": [
      {
        "id": 1,
        "name": "홍길동",
        "sex": "MAN",
        "email": "student@gsm.hs.kr",
        "grade": 1,
        "classNum": 1,
        "number": 1,
        "studentNumber": 1101,
        "major": "SW_DEVELOPMENT",
        "role": "GENERAL_STUDENT",
        "dormitoryFloor": 3,
        "dormitoryRoom": 301,
        "majorClub": {
          "id": 1,
          "name": "SW개발동아리",
          "type": "MAJOR_CLUB"
        },
        "autonomousClub": null
      }
    ]
  }
}

오류 응답

상태 코드	설명
`401 Unauthorized`	API 키가 유효하지 않거나 만료됨
`403 Forbidden`	권한 범위 부족
`429 Too Many Requests`	단위 시간에 너무 많은 요청량 발생
`400 Bad Request`	잘못된 요청 파라미터

사용 예제

다음은 여러 언어에서 학생 데이터를 조회하는 예제입니다.

const axios = require('axios');

async function getStudents(studentId) {
try {
  const response = await axios.get('https://api.datagsm.com/v1/students', {
    headers: {
      'X-API-KEY': 'your-api-key-here',
    },
    params: {
      studentId: studentId,
    },
  });
  return response.data;
} catch (error) {
  console.error('Error:', error.message);
  throw error;
}
}

import requests

def get_student(student_id):
  try:
      response = requests.get(
          'https://api.datagsm.com/v1/students',
          headers={'X-API-KEY': 'your-api-key-here'},
          params={'studentId': student_id}
      )
      response.raise_for_status()
      return response.json()
  except requests.exceptions.RequestException as e:
      print(f'Error: {e}')
      raise

import java.net.http.*;
import java.net.URI;

public class StudentAPI {
  public static String getStudents(Long studentId) throws Exception {
      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
          .uri(URI.create("https://api.datagsm.com/v1/students?studentId=" + studentId))
          .header("X-API-KEY", "your-api-key-here")
          .GET()
          .build();

      HttpResponse<String> response = client.send(request,
          HttpResponse.BodyHandlers.ofString());
      return response.body();
  }
}

import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
import java.net.URI

fun getStudents(studentId: Long): String {
  val client = HttpClient.newHttpClient()
  val request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.datagsm.com/v1/students?studentId=${studentId}"))
      .header("X-API-KEY", "your-api-key-here")
      .GET()
      .build()

  val response = client.send(request, HttpResponse.BodyHandlers.ofString())
  return response.body()
}