OpenApi 연동 가이드
도담도담(dodam-api.b1nd.com)에서 공개적으로 사용할 수 있는 api를 정리한 문서입니다.
목차
유저 데이터 조회
외박
심야자습
1. 개요
OpenApi는 도담도담(dodam-api.b1nd.com)에서 외부 서비스·서드파티 개발자가 활용할 수 있도록 제공되는 API 모음입니다. 도담도담 내부 데이터 중 공개해도 무방한 정보를 외부 서비스·개인 프로젝트에서 활용할 수 있도록 제공하며, 이 문서는 해당 API들을 앱·웹·서드파티 개발자를 대상으로 설명합니다.
OpenApi는 다음과 같은 특징을 가집니다.
- DAuth 앱 등록 필요 — 사용에 앞서 DAuth에 앱을 등록해야 합니다.
- 읽기 전용(GET) — 데이터를 조회하는 용도로만 사용되며, 생성·수정·삭제는 제공하지 않습니다.
2. 전체 흐름
plaintext
DAuth 앱 등록 → 클라이언트 → GET 요청 (인증 정보 포함) → 공개 데이터 응답
3. 인증
OpenApi는 HTTP Basic 인증 방식을 사용합니다. 아래 절차에 따라 인증 정보를 만들어 요청 헤더에 담아주세요.
- DAuth 앱 등록 — DAuth에서 앱을 등록하고 Client ID와 Client Secret을 발급받습니다. (자세한 절차는 DAuth 페이지를 참고해주세요.)
- Base64 인코딩 — 발급받은 값을
Client_id:Client_secret형식(콜론으로 연결)으로 이어 붙인 뒤 Base64로 인코딩합니다. - 요청 헤더에 추가 — 인코딩한 값을
Authorization헤더에Basic스킴으로 담아 요청합니다.
요청 헤더 예시
http
Authorization: Basic <Base64로 인코딩한 값>
4. 응답 공통 포멧
모든 응답은 아래 래퍼로 감싸집니다. 성공·에러 모두 같은 구조이며, 에러일 때만 code가 포함되고 data가 제외됩니다.
| 필드 | 타입 | 설명 |
|---|---|---|
status | int | HTTP 상태 코드 (예: 200, 404) — 항상 포함 |
message | string | 사용자용 메시지 (한국어) — 항상 포함 |
data | T | 실제 데이터. 값이 없으면 키 자체가 생략됩니다 |
code | string | 에러 코드. 성공 응답에는 없습니다 |
성공 응답
json
{"status": 200,"message": "전체 심야자습 인원을 조회했어요.","data": {"total": 0}}
에러 응답
json
{"status": 500,"message": "서비스 요청을 처리하지 못했어요."}
5. 유저 검색
이름 키워드로 유저 목록을 검색하는 Api입니다.
| 항목 | 값 |
|---|---|
| Method | GET |
| URL | /user/openapi/search |
Request
Query Parameters
| 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
keyword | String | X | 검색 키워드(이름) |
Response
json
{"status": 200, // 응답 상태 코드 (HTTP status)"message": "사용자 목록 조회에 성공했습니다.", // 응답 메시지"data": [{"publicId": "UUID", // 사용자 공개 식별자 (UUID)"username": "string", // 사용자 아이디 (로그인 ID)"name": "string", // 사용자 실명"phone": "string", // 전화번호 ('-' 없이 숫자만)"profileImage": "string", // 프로필 이미지 URL"status": "ACTIVE", // 계정 상태 (ACTIVE, DEACTIVATED, PENDING)"roles": ["STUDENT" // 사용자 권한 목록 (STUDENT, TEACHER, ADMIN 등)],"student": { // 학생 정보 (역할이 STUDENT인 경우)"grade": 0, // 학년 (1 ~ 3)"room": 0, // 반 (1 ~ 4)"number": 0, // 번호"isGraduated": false // 졸업 여부},"teacher": { // 교사 정보 (역할이 TEACHER인 경우, 아니면 null)"position": "string" // 직책 (담임교사, 학년부장 등)},"createdAt": "2026-05-20T00:05:42.894Z" // 계정 생성 일시 (ISO 8601, UTC)}],"code": "SUCCESS" // 응답 코드 (SUCCESS, USER_NOT_FOUND 등)}
6. 외박자 명단 조회
입력한 날짜값을 기준으로 외박을 하는 학생들을 조회하는 api입니다.
| 항목 | 값 |
|---|---|
| Method | GET |
| URL | /out-sleeping/openapi/search |
Query Parameters
| 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
date | String | O | 검색할 날짜(yyyy-mm-dd) |
Response
json
{"status": 200, // 응답 상태 코드 (HTTP status)"message": "외박자 명단 조회에 성공했습니다.", // 응답 메시지"data": {"content": [{"publicId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // 외박 신청 공개 식별자 (UUID)"reason": "string", // 외박 사유"status": "PENDING", // 외박 상태 (PENDING, ALLOWED, REJECTED)"student": { // 외박 신청 학생 정보"name": "string", // 학생 이름"grade": 0, // 학년 (1 ~ 3)"room": 0, // 반 (1 ~ 4)"number": 0 // 번호},"startAt": "2026-05-20", // 외박 시작 날짜 (yyyy-MM-dd)"endAt": "2026-05-20" // 외박 종료 날짜 (yyyy-MM-dd)}],},"code": "SUCCESS" // 응답 코드 (SUCCESS, OUT_SLEEPING_NOT_FOUND 등)}
7. 심야자습 명단 조회
입력한 유형(type)과 날짜(date)를 기준으로 승인된 심야자습 명단을 조회합니다.
| 항목 | 값 |
|---|---|
| Method | GET |
| URL | /nightstudy/openapi/search |
Query Parameters
| 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
type | String | O | 심야자습 유형 (PERSONAL / PROJECT) |
date | String | O | 검색할 날짜(yyyy-mm-dd) |
Response
json
{"name": "String?", // 프로젝트 심야자습 이름 (PROJECT만 값 있음, PERSONAL이면 항상 null)"description": "String", // 심야자습 사유/내용"period": "Int", // 진행 교시"type": "NightStudyType", // 심야자습 유형 (PERSONAL / PROJECT enum)"startAt": "LocalDate", // 시작 날짜 (yyyy-MM-dd)"endAt": "LocalDate", // 종료 날짜 (yyyy-MM-dd)"status": "NightStudyStatusType", // 심야자습 승인 상태 (ALLOWED / PENDING / REJECTED enum)"leader": "Student", // 대표(신청) 학생 정보"members": "List<Student>" // 참여 학생 목록}
Student
json
{"name": String, // 이름"grade": Int, // 학년"room": Int, // 반"number": Int, // 번호"attended": Boolean, // 해당 날짜 출석 여부}