API 레퍼런스 개요
소개
이 섹션에서는 의료 정보 관리 애플리케이션 개발에 필요한 백엔드 API의 상세 명세를 제공합니다. 각 API 엔드포인트의 요청 형식, 응답 형식, 인증 요구사항 및 에러 처리 방법을 설명합니다.
API 기본 정보
기본 URL
모든 API 요청은 다음 기본 URL을 사용합니다:
- 개발 환경:
https:// - 스테이징 환경:
https:// - 프로덕션 환경:
https://
인증
보호된 API에 접근하려면 Bearer 토큰을 Authorization 헤더에 포함해야 합니다.
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
요청 형식
- API 요청 본문은 JSON 형식을 사용합니다.
- Content-Type 헤더는
application/json으로 설정해야 합니다.
응답 형식
API 응답은 다음과 같은 일관된 형식을 따릅니다:
- 단일 객체 요청의 경우, 객체가 직접 반환됩니다.
- 컬렉션 요청의 경우,
items배열과metadata객체가 포함됩니다. - 에러 응답의 경우,
code,message,detail등의 필드가 포함됩니다.
도메인별 API
본 API 레퍼런스는 다음과 같은 도메인별 API를 포함합니다:
| 도메인 | 설명 | 문서 링크 |
|---|---|---|
| 관리자 (Admin) | 관리자 기능 | 관리자 API |
| 인증 (Auth) | 인증 및 토큰 관리 | 인증 API |
| 사용자 관리 (User Management) | 앱 사용자 관리 | 사용자 관리 API |
| 연구 (Research) | 연구 데이터 관리 | 연구 API |
| 그룹 (Group) | 그룹 관리 | 그룹 API |
| 사이트 (CRM Site) | 사이트/MD 정보 관리 | 사이트 API |
| 지원 (CRM Support) | 환자 지원 관리 | 지원 API |
| 사용자 (CRM User) | CRM 사용자 정보 | 사용자 API |
API 호출 예시
각 API 설명에는 다음과 같은 형식으로 호출 예시가 포함됩니다:
cURL 예시
curl -X GET "https://api-dev.example.com/v1/patients/me" \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
-H "Content-Type: application/json"
에러 처리
API 호출 시 발생할 수 있는 일반적인 에러 코드는 다음과 같습니다:
| HTTP 상태 코드 | 설명 |
|---|---|
| 400 Bad Request | 잘못된 요청 파라미터나 본문 |
| 401 Unauthorized | 인증 필요 또는 인증 실패 |
| 403 Forbidden | 접근 권한 없음 |
| 404 Not Found | 리소스를 찾을 수 없음 |
| 409 Conflict | 리소스 충돌 (예: 중복된 리소스 생성 시도) |
| 429 Too Many Requests | 요청 횟수 제한 초과 |
| 500 Internal Server Error | 서버 내부 오류 |
제한 사항
- API 요청 속도는 IP당 분당 100회로 제한됩니다.
- 대량의 데이터 요청은 페이지네이션을 사용해야 합니다.
- 파일 업로드 크기는 최대 10MB로 제한됩니다.
도움말 및 지원
API 사용 중 문제가 발생하면 API 가이드라인 문서를 참조하세요.