콘텐츠로 이동

4. API Specification

4.1 API 설계 원칙

원칙 설명
RESTful 리소스 기반 URL, HTTP 메서드 활용
JSON 요청/응답 본문은 JSON 형식
페이지네이션 page, size 파라미터 (기본 0, 20)
응답 래퍼 ApiResponse<T> 통일 형식
Swagger SpringDoc OpenAPI 자동 문서 생성

응답 형식

{
  "success": true,
  "data": { ... },
  "message": "OK"
}

페이지 응답

{
  "success": true,
  "data": {
    "content": [ ... ],
    "totalElements": 100,
    "totalPages": 5,
    "page": 0,
    "size": 20
  }
}

API 문서 (Swagger)

로컬 개발: http://localhost:8080/swagger-ui.html

4.2 인증

대상 방식 헤더/파라미터
관리자 API API Key X-Api-Key 헤더
사용자 API JWT Bearer Authorization: Bearer {token}
공개 API 없음 —

4.3 시험 관리 API (Admin)

Method Endpoint 설명
GET /api/exams 시험 목록 (페이지네이션, 검색)
GET /api/exams/{examCd} 시험 상세
POST /api/exams 시험 등록
PUT /api/exams/{examCd} 시험 수정
DELETE /api/exams/{examCd} 시험 삭제
PUT /api/exams/{examCd}/status 상태 변경
POST /api/exams/{examCd}/rescore 재채점

검색 파라미터:

파라미터 타입 설명
page int 페이지 번호 (0부터)
size int 페이지 크기
keyword String 시험명 검색
examType String 시험 유형 필터
examYear Integer 시험 년도 필터
Method Endpoint 설명
GET /api/exams/{examCd}/subjects 과목 목록
POST /api/exams/{examCd}/subjects 과목 등록/수정 (일괄)
DELETE /api/exams/{examCd}/subjects/{subjectCd} 과목 삭제
Method Endpoint 설명
GET /api/exams/{examCd}/answers 정답 목록
POST /api/exams/{examCd}/answers 정답 등록/수정 (일괄)

4.4 응시자 관리 API (Admin)

Method Endpoint 설명
GET /api/exams/{examCd}/applicants 응시자 목록
GET /api/exams/{examCd}/applicants/{id} 응시자 상세
POST /api/exams/{examCd}/applicants 응시자 등록
PUT /api/exams/{examCd}/applicants/{id} 응시자 수정
DELETE /api/exams/{examCd}/applicants/{id} 응시자 삭제

4.5 데이터 가져오기 API (Admin)

Method Endpoint 설명
POST /api/import/excel/answer-key/preview 정답지 미리보기
POST /api/import/excel/answer-key/submit 정답지 확정
POST /api/import/excel/applicants/preview 응시자 미리보기
POST /api/import/excel/applicants/submit 응시자 확정
Method Endpoint 설명
POST /api/import/json/questions 문항 데이터 업로드

파일 업로드

multipart/form-data 형식, 최대 20MB

4.6 통계 API (Admin)

Method Endpoint 설명
GET /api/statistics/dashboard 종합 대시보드
GET /api/statistics/exams/{examCd} 시험별 기본 통계
GET /api/statistics/exams/{examCd}/questions 문항별 분석
GET /api/statistics/exams/{examCd}/weakness 취약점 분석
GET /api/statistics/exams/{examCd}/area 영역별 분석
GET /api/statistics/exams/{examCd}/subjects/{subjectCd}/discrimination 변별도 분석
GET /api/statistics/trend 성적 추이

4.7 문제은행 / 문제세트 API (Admin)

Method Endpoint 설명
GET /api/question-bank 그룹 목록
GET /api/question-bank/{groupId} 그룹 상세
POST /api/question-bank 그룹 생성
PUT /api/question-bank/{groupId} 그룹 수정
DELETE /api/question-bank/{groupId} 그룹 삭제
POST /api/question-bank/{groupId}/items 문항 추가
PUT /api/question-bank/{groupId}/items/{itemId} 문항 수정
DELETE /api/question-bank/{groupId}/items/{itemId} 문항 삭제
Method Endpoint 설명
GET /api/question-sets 세트 목록
GET /api/question-sets/{setId} 세트 상세
POST /api/question-sets 세트 생성
PUT /api/question-sets/{setId} 세트 수정
DELETE /api/question-sets/{setId} 세트 삭제

4.8 공지사항 API (Admin)

Method Endpoint 설명
GET /api/exams/{examCd}/notices 공지사항 목록
POST /api/exams/{examCd}/notices 등록
PUT /api/exams/{examCd}/notices/{noticeId} 수정
DELETE /api/exams/{examCd}/notices/{noticeId} 삭제

4.9 사용자 API (User)

Method Endpoint 설명
GET /api/user/exams 참여 가능 시험 목록
GET /api/user/exams/{examCd} 시험 상세
POST /api/user/exams/{examCd}/submit 답안 제출 (채점)
GET /api/user/exams/{examCd}/result 채점 결과
GET /api/user/exams/{examCd}/analysis 성적 분석
GET /api/user/history 응시 이력
GET /api/user/profile 프로필 조회
PUT /api/user/profile 프로필 수정

4.10 시스템 API

Method Endpoint 설명
GET /api/health 헬스체크
POST /api/admin/verify 관리자 인증 검증

4.11 에러 코드

HTTP 상태 의미 예시
200 성공 정상 응답
201 생성 완료 시험/응시자 등록
400 잘못된 요청 필수 파라미터 누락
401 인증 실패 API Key/JWT 누락 또는 만료
403 권한 없음 접근 권한 부족
404 리소스 없음 시험/응시자 미존재
409 충돌 중복 시험코드
500 서버 오류 내부 오류