Repository navigation
Study Planner API Spec
wcorn edited this page Apr 1, 2026
·
18 revisions
Base URL: /api
모든 API는 인증 필요 (Authorization: Bearer {accessToken}).
성공
{
"code": "요청에 성공하였습니다.",
"data": { ... }
}에러
{
"code": "SP-ERR-001",
"message": "존재하지 않는 리소스입니다."
}| 코드 | HTTP | 메시지 |
|---|---|---|
| SP-ERR-001 | 404 | 존재하지 않는 리소스입니다 |
| SP-ERR-002 | 400 | 유효하지 않은 요청입니다 |
| SP-ERR-003 | 409 | 참조하는 데이터가 존재하여 삭제할 수 없습니다 |
| SP-ERR-004 | 409 | 현재 상태에서 수행할 수 없는 작업입니다 |
| SP-ERR-005 | 400 | 배분 비율 합계가 100%를 초과합니다 |
| Method | Path | 설명 |
|---|---|---|
| GET | /api/categories |
카테고리 목록 |
| POST | /api/categories |
카테고리 생성 |
| PUT | /api/categories/{id} |
카테고리 수정 |
| DELETE | /api/categories/{id} |
카테고리 삭제 |
| Method | Path | 설명 |
|---|---|---|
| GET | /api/goals |
목표 목록 |
| POST | /api/goals |
목표 생성 |
| GET | /api/goals/{id} |
목표 상세 (마일스톤, 연결된 자료/할일 포함) |
| PUT | /api/goals/{id} |
목표 수정 |
| DELETE | /api/goals/{id} |
목표 삭제 |
| PATCH | /api/goals/{id}/status |
목표 상태 변경 |
| POST | /api/goals/{id}/milestones |
마일스톤 추가 |
| PUT | /api/goals/{goalId}/milestones/{id} |
마일스톤 수정 |
| DELETE | /api/goals/{goalId}/milestones/{id} |
마일스톤 삭제 |
| PATCH | /api/goals/{goalId}/milestones/{id}/complete |
마일스톤 완료 |
| Method | Path | 설명 |
|---|---|---|
| GET | /api/fixed-schedules |
고정 일정 목록 |
| POST | /api/fixed-schedules |
고정 일정 생성 |
| PUT | /api/fixed-schedules/{id} |
고정 일정 수정 |
| DELETE | /api/fixed-schedules/{id} |
고정 일정 삭제 |
| Method | Path | 설명 |
|---|---|---|
| GET | /api/routines |
루틴 목록 |
| POST | /api/routines |
루틴 생성 |
| GET | /api/routines/{id} |
루틴 상세 (스트릭 포함) |
| PUT | /api/routines/{id} |
루틴 수정 |
| DELETE | /api/routines/{id} |
루틴 삭제 |
| PATCH | /api/routines/{id}/status |
루틴 상태 변경 |
| POST | /api/routines/{id}/check |
루틴 체크 |
| DELETE | /api/routines/{id}/check |
루틴 체크 취소 |
| POST | /api/routines/{id}/exceptions |
예외일 추가 |
| DELETE | /api/routines/{id}/exceptions/{exceptionId} |
예외일 삭제 |
| Method | Path | 설명 |
|---|---|---|
| GET | /api/todos |
할 일 목록 (필터: status, priority, categoryId, hasDeadline) |
| POST | /api/todos |
할 일 생성 |
| PUT | /api/todos/{id} |
할 일 수정 |
| DELETE | /api/todos/{id} |
할 일 삭제 |
| PATCH | /api/todos/{id}/complete |
할 일 완료 |
| Method | Path | 설명 |
|---|---|---|
| GET | /api/materials |
학습 자료 목록 |
| POST | /api/materials |
학습 자료 생성 |
| GET | /api/materials/{id} |
학습 자료 상세 (학습 단위, 진행률 포함) |
| PUT | /api/materials/{id} |
학습 자료 수정 |
| DELETE | /api/materials/{id} |
학습 자료 삭제 |
| PATCH | /api/materials/{id}/pause |
일시정지 |
| PATCH | /api/materials/{id}/resume |
재개 |
| POST | /api/materials/{id}/units |
학습 단위 추가 |
| POST | /api/materials/{id}/units/batch |
학습 단위 일괄 등록 |
| PUT | /api/materials/{materialId}/units/{id} |
학습 단위 수정 |
| DELETE | /api/materials/{materialId}/units/{id} |
학습 단위 삭제 |
| POST | /api/materials/{materialId}/units/{id}/dependencies |
의존성 추가 |
| DELETE | /api/materials/{materialId}/units/{unitId}/dependencies/{depId} |
의존성 삭제 |
| PUT | /api/materials/{id}/allocation |
배분 비율 설정 |
| PUT | /api/materials/{id}/review-config |
복습 설정 오버라이드 |
| Method | Path | 설명 |
|---|---|---|
| GET | /api/calendar/daily |
일간 스케줄 조회 |
| GET | /api/calendar/weekly |
주간 스케줄 조회 |
| GET | /api/calendar/monthly |
월간 요약 조회 |
| PATCH | /api/calendar/blocks/{blockId}/complete |
블록 완료 |
| POST | /api/calendar/blocks/{blockId}/postpone |
블록 미루기 |
| Method | Path | 설명 |
|---|---|---|
| POST | /api/reviews/{id}/feedback |
복습 피드백 제출 |
| Method | Path | 설명 |
|---|---|---|
| GET | /api/rescheduling/options |
리스케줄링 선택지 조회 |
| POST | /api/rescheduling/apply |
리스케줄링 적용 |
| Method | Path | 설명 |
|---|---|---|
| GET | /api/dashboard/summary |
대시보드 요약 |
| GET | /api/dashboard/streaks |
스트릭 정보 |
| GET | /api/dashboard/heatmap |
히트맵 데이터 |
| GET | /api/dashboard/statistics |
통계 |
| Method | Path | 설명 |
|---|---|---|
| GET | /api/reflections |
회고 조회 |
| POST | /api/reflections |
회고 작성 |
| PUT | /api/reflections/{id} |
회고 수정 |
| Method | Path | 설명 |
|---|---|---|
| GET | /api/preferences |
설정 조회 |
| PUT | /api/preferences |
설정 수정 |
| GET | /api/preferences/priority-rules |
우선순위 규칙 조회 |
| PUT | /api/preferences/priority-rules |
우선순위 규칙 수정 |
일간 스케줄을 조회한다. 스케줄이 없거나 dirty 상태이면 엔진이 자동 생성한다.
Query Parameters
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| date | string (YYYY-MM-DD) | N | 조회 날짜 (기본: 오늘) |
Response 200
{
"code": "요청에 성공하였습니다.",
"data": {
"date": "2026-04-02",
"totalBlocks": 9,
"completedBlocks": 3,
"blocks": [
{
"id": 101,
"blockType": "ROUTINE",
"referenceId": 1,
"title": "헬스",
"categoryName": "건강",
"categoryColor": "#4CAF50",
"startTime": "07:00",
"endTime": "08:30",
"status": "COMPLETED"
},
{
"id": 102,
"blockType": "ROUTINE",
"referenceId": 2,
"title": "영어",
"categoryName": "어학",
"categoryColor": "#2196F3",
"startTime": "09:00",
"endTime": "09:30",
"status": "COMPLETED"
},
{
"id": 103,
"blockType": "FIXED",
"referenceId": 1,
"title": "자료구조 수업",
"startTime": "10:00",
"endTime": "12:00",
"status": "COMPLETED"
},
{
"id": 104,
"blockType": "REVIEW",
"referenceId": 45,
"title": "이펙티브 자바 #12 (복습 2회차)",
"categoryName": "프로그래밍",
"categoryColor": "#FF9800",
"startTime": "13:00",
"endTime": "13:30",
"status": "SCHEDULED"
},
{
"id": 105,
"blockType": "STUDY",
"referenceId": 15,
"title": "이펙티브 자바 #15",
"categoryName": "프로그래밍",
"categoryColor": "#FF9800",
"startTime": "13:30",
"endTime": "14:00",
"status": "SCHEDULED"
}
],
"warnings": [
{
"type": "DEADLINE_CLOSE",
"message": "스프링 입문 데드라인까지 여유가 5일 남았습니다."
}
]
}
}블록을 완료 처리한다. 블록 유형에 따라 후속 처리가 다르다.
Response 200 (STUDY 블록)
{
"code": "요청에 성공하였습니다.",
"data": {
"blockId": 105,
"status": "COMPLETED",
"effect": {
"type": "REVIEW_CREATED",
"message": "복습 6회가 자동 생성되었습니다.",
"nextReviewDate": "2026-04-03"
},
"dailyProgress": {
"totalBlocks": 9,
"completedBlocks": 4
}
}
}Response 200 (REVIEW 블록)
{
"code": "요청에 성공하였습니다.",
"data": {
"blockId": 104,
"status": "COMPLETED",
"feedbackRequired": true,
"reviewId": 45
}
}복습 블록은 완료 후 피드백 제출이 필요하다.
복습 난이도 피드백을 제출한다.
Request
{
"difficulty": "EASY"
}- difficulty:
EASY/NORMAL/HARD
Response 200
{
"code": "요청에 성공하였습니다.",
"data": {
"reviewId": 45,
"difficulty": "EASY",
"nextReview": {
"sequence": 3,
"scheduledDate": "2026-04-08",
"adjustedInterval": "6일 (기존 4일 → 쉬움 반영)"
}
}
}블록을 미룬다.
Request
{
"strategy": "TOMORROW"
}- strategy:
TOMORROW/THIS_WEEK
Response 200
{
"code": "요청에 성공하였습니다.",
"data": {
"blockId": 105,
"postponedTo": "2026-04-03",
"dailyProgress": {
"totalBlocks": 8,
"completedBlocks": 4
}
}
}연속 미완료 시 리스케줄링 선택지를 조회한다.
Response 200
{
"code": "요청에 성공하였습니다.",
"data": {
"missedDays": 3,
"missedItems": 12,
"options": [
{
"strategy": "POSTPONE",
"label": "뒤로 밀기",
"description": "전체 일정 3일 후퇴",
"deadlineFeasible": true,
"newEstimatedCompletion": "2026-07-04"
},
{
"strategy": "COMPRESS",
"label": "압축",
"description": "남은 기간에 밀린 양 분산",
"dailyIncreasePercent": 20,
"deadlineFeasible": true,
"newEstimatedCompletion": "2026-07-01"
},
{
"strategy": "KEEP_DEADLINE",
"label": "데드라인 고정",
"description": "하루 학습량 증가로 기존 일정 유지",
"dailyIncreasePercent": 35,
"deadlineFeasible": false,
"warning": "하루 가용시간 대비 학습량이 과다합니다"
}
]
}
}리스케줄링 전략을 적용한다.
Request
{
"strategy": "COMPRESS"
}Response 200
{
"code": "요청에 성공하였습니다.",
"data": {
"strategy": "COMPRESS",
"affectedDays": 87,
"newDailyStudyMinutes": 144
}
}학습 자료를 생성한다.
Request
{
"title": "이펙티브 자바",
"type": "BOOK",
"categoryId": 1,
"goalId": 1,
"deadline": "2026-07-01",
"deadlineMode": "DEADLINE",
"units": [
{ "title": "아이템 1 - 생성자 대신 정적 팩터리 메서드", "estimatedMinutes": 30 },
{ "title": "아이템 2 - 생성자에 매개변수가 많다면 빌더를 고려하라", "estimatedMinutes": 30 }
]
}Response 201
{
"code": "요청에 성공하였습니다.",
"data": {
"id": 1,
"title": "이펙티브 자바",
"type": "BOOK",
"totalUnits": 2,
"completedUnits": 0,
"deadlineMode": "DEADLINE",
"deadline": "2026-07-01",
"dailyRequired": 1,
"estimatedCompletion": "2026-06-28"
}
}대시보드 요약을 조회한다.
Response 200
{
"code": "요청에 성공하였습니다.",
"data": {
"goals": [
{
"id": 1,
"title": "백엔드 취업 준비",
"progressPercent": 32,
"paceStatus": "ON_TRACK"
}
],
"thisWeek": {
"studyMinutes": 860,
"reviewCompletionRate": 85
},
"streaks": {
"overall": { "currentCount": 23, "longestCount": 30 },
"routines": [
{ "routineId": 1, "title": "헬스", "currentCount": 15 },
{ "routineId": 2, "title": "영어", "currentCount": 23 }
]
},
"todayProgress": {
"totalBlocks": 9,
"completedBlocks": 4
}
}
}연간 히트맵 데이터를 조회한다.
Query Parameters
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| year | int | N | 연도 (기본: 올해) |
Response 200
{
"code": "요청에 성공하였습니다.",
"data": {
"year": 2026,
"days": [
{ "date": "2026-01-01", "achievementRate": 0 },
{ "date": "2026-01-02", "achievementRate": 80 },
{ "date": "2026-01-03", "achievementRate": 100 }
]
}
}기간별 통계를 조회한다.
Query Parameters
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| period | string | N | DAILY / WEEKLY / MONTHLY (기본: WEEKLY) |
| startDate | string | N | 시작일 |
| endDate | string | N | 종료일 |
Response 200
{
"code": "요청에 성공하였습니다.",
"data": {
"period": "WEEKLY",
"totalStudyMinutes": 860,
"totalReviewMinutes": 240,
"reviewCompletionRate": 85,
"categoryBreakdown": [
{ "categoryId": 1, "name": "프로그래밍", "color": "#FF9800", "minutes": 680, "percent": 62 },
{ "categoryId": 2, "name": "알고리즘", "color": "#9C27B0", "minutes": 420, "percent": 38 }
]
}
}사용자 설정을 수정한다.
Request
{
"wakeTime": "07:00",
"sleepTime": "24:00",
"studyTimePreference": "MORNING",
"focusMinutes": 50,
"breakMinutes": 10,
"restDays": ["SUN"],
"skipHolidays": false,
"defaultReviewIntervals": [1, 2, 3, 7, 15, 30],
"defaultMissedPolicy": "IMMEDIATE",
"streakFreezePerMonth": 2
}Response 200
{
"code": "요청에 성공하였습니다.",
"data": { ... }
}| Phase | API |
|---|---|
| 1 | categories, goals, fixed-schedules, routines (기본), todos, materials, calendar/daily, preferences |
| 2 | reviews/feedback, calendar/weekly, calendar/monthly, rescheduling, calendar/blocks/postpone |
| 3 | dashboard (summary, streaks, heatmap, statistics), reflections |
| 4 | Google Calendar 연동 API, 학습 자료 OCR/URL 파싱 API, 알림 API |