프로젝트 데이터 OpenAPI

개요

프로젝트 데이터 OpenAPI는 동아리에서 진행하는 프로젝트 데이터를 간단한 HTTP 요청을 통하여 서비스에 통합할 수 있도록 돕습니다. 해당 REST API를 호출하여 기본적인 프로젝트 데이터를 획득할 수 있습니다.

인증

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

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

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

엔드포인트

GET /v1/projects

권한 범위

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

요청 파라미터

파라미터	타입	필수 여부	설명	예시
`projectId`	`Long`	선택	프로젝트 ID	`1`
`projectName`	`String`	선택	프로젝트 이름	`DataGSM 프로젝트`
`clubId`	`Long`	선택	동아리 ID	`1`
`page`	`Int`	선택	페이지 번호 (기본값: 0)	`0`
`size`	`Int`	선택	페이지 크기 (기본값: 100)	`100`
`sortBy`	`ProjectSortBy`	선택	정렬 기준 (ID, NAME)	`NAME`
`sortDirection`	`SortDirection`	선택	정렬 방향 (ASC, DESC) (기본값: ASC)	`ASC`

응답 형식

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

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

data 객체

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

필드	타입	설명	예시
`totalPages`	`Int`	전체 페이지 수	`1`
`totalElements`	`Long`	전체 프로젝트 수	`20`
`projects`	`List<ProjectResDto>`	프로젝트 목록	-

프로젝트 객체 (ProjectResDto)

각 프로젝트 객체는 다음 필드를 포함합니다.

필드	타입	설명	예시
`id`	`Long`	프로젝트 ID	`1`
`name`	`String`	프로젝트 이름	`DataGSM 프로젝트`
`description`	`String`	프로젝트 설명	`학교 데이터를 제공하는 API 서비스`
`club`	`ClubSummaryDto?`	프로젝트 소유 동아리 데이터 (없는 경우 `null`)	-
`participants`	`List<ParticipantInfoDto>`	프로젝트 참가자 목록	-

동아리 요약 객체 (ClubSummaryDto)

프로젝트 응답에 포함된 동아리 데이터는 다음 필드를 포함합니다.

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

참가자 데이터 객체 (ParticipantInfoDto)

프로젝트 응답에 포함된 참가자 데이터는 다음 필드를 포함합니다.

필드	타입	설명	예시
`id`	`Long`	학생 ID	`1`
`name`	`String`	학생 이름	`홍길동`
`email`	`String`	학생 이메일	`s24080@gsm.hs.kr`
`studentNumber`	`Int?`	학번 (졸업/자퇴 시 `null`)	`1201`
`major`	`Major?`	학과 (졸업/자퇴 시 `null`, 값: `SW_DEVELOPMENT`, `SMART_IOT`, `AI`)	`SW_DEVELOPMENT`
`sex`	`Sex`	성별 (`MAN`, `WOMAN`)	`MAN`

요청 예시

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

정렬을 포함한 요청 예시

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

응답 예시

{
  "status": "OK",
  "code": 200,
  "message": "OK",
  "data": {
    "totalPages": 1,
    "totalElements": 2,
    "projects": [
      {
        "id": 1,
        "name": "DataGSM 프로젝트",
        "description": "학교 데이터를 제공하는 API 서비스",
        "club": {
          "id": 1,
          "name": "SW개발동아리",
          "type": "MAJOR_CLUB"
        },
        "participants": [
          {
            "id": 1,
            "name": "홍길동",
            "email": "s24080@gsm.hs.kr",
            "studentNumber": 1201,
            "major": "SW_DEVELOPMENT",
            "sex": "MAN"
          },
          {
            "id": 2,
            "name": "김철수",
            "email": "s24081@gsm.hs.kr",
            "studentNumber": 1202,
            "major": "SMART_IOT",
            "sex": "MAN"
          }
        ]
      }
    ]
  }
}

오류 응답

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

사용 예제

다음은 여러 언어에서 프로젝트 데이터를 조회하는 예제입니다.

const axios = require('axios');

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

import requests

def get_project(project_id):
  try:
      response = requests.get(
          'https://api.datagsm.com/v1/projects',
          headers={'X-API-KEY': 'your-api-key-here'},
          params={'projectId': project_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 ProjectAPI {
  public static String getProjects(Long projectId) throws Exception {
      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
          .uri(URI.create("https://api.datagsm.com/v1/projects?projectId=" + projectId))
          .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 getProjects(projectId: Long): String {
  val client = HttpClient.newHttpClient()
  val request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.datagsm.com/v1/projects?projectId=${projectId}"))
      .header("X-API-KEY", "your-api-key-here")
      .GET()
      .build()

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