Download OpenAPI specification:
EWB를 통한 workbook 제작을 사용하기 위한 API입니다.
EWB API를 활용한 개발을 시작하신다면, 아래의 안내를 먼저 확인해보세요.
EWB API는 RESTful 구조를 기반으로 합니다.
RESTful API는 표준 HTTP 메서드를 사용하여 자원에 접근하고 조작할 수 있는 방법을 제공합니다.
EWB의 개발 가이드는 수시로 업데이트됩니다. 업데이트 내용은 API 변경 이력을 통해 확인할 수 있습니다.
EWB API는 JWT 토큰을 통해 사용자 인증을 수행합니다.
요청 시 Authorization 헤더에 Bearer {JWT 토큰} 형식으로 전달해야 합니다.
인증 방식에 따라 /admin/v1 및 /main/v1와 같은 경로로 구분됩니다.
어드민 API
경로: /admin/v1
사용자 인증: 어드민 API는 사용자 ID와 비밀번호를 통해 인증하며, 인증 성공 시 액세스 토큰, 리프레시 토큰, 토큰 만료 시간이 반환됩니다.
외부 API
경로: /main/v1
사용자 인증: 외부 API는 OAuth2 프로토콜을 사용하여 인증됩니다. OAuth2 인증 API는 /oauth2 경로로 시작합니다.
어드민 인증은 /admin/v1/login API를 통해 수행됩니다.
인증이 성공하면 액세스 토큰, 리프레시 토큰, 토큰 만료 시간이 반환됩니다. 이후의 요청에서는 Authorization 헤더에 Bearer {JWT 토큰}을 포함해야 합니다.
현재 지원되는 OAuth2 인증 제공자(registrationId)는 kakao입니다. OAuth2 인증 절차는 다음과 같습니다.
/oauth2/authorization/{registrationId} 경로로 GET 요청을 보내면, 해당 OAuth2 Provider의 로그인 페이지로 리다이렉트됩니다.EWB 서버에서는 사용자가 OAuth2 Provider에서 인증을 완료하면, 액세스 토큰과 리프레시 토큰 생성까지의 과정(2번 ~ 5번)을 내부적으로 처리하고 있습니다.
사용자가 로그인 페이지에서 인증을 완료하면 EWB 서버는 클라이언트에게 액세스 토큰, 리프레시 토큰, 토큰 만료 시간을 반환합니다.
| 코드 | 설명 |
|---|---|
| 200 OK | 정상 |
| 400 Bad Request | 파라미터 오류 |
| 401 Unauthorized | 인증 오류 |
| 404 Not Found | 존재하지 않는 요청 |
| 50x Server Error | 서버 오류 |
특별한 경우를 제외하고 모든 응답은 JSON 형식으로 반환됩니다.
{
"accessToken": "accessToken",
"accessTokenExpireTime": "2024-11-01T13:11:54.375",
"refreshToken": "refreshToken",
"refreshTokenExpireTime": "2024-11-01T12:56:54.375"
}
EWB API를 사용할 때 발생할 수 있는 에러를 살펴보세요.
EWB prefix가 붙은 에러 코드는 세부 에러 코드가 정의되지 않은 경우 사용됩니다.
| 코드 | 에러 메시지(reason) | 설명 |
|---|---|---|
| EWB400 | 잘못된 요청입니다. | 요청 값이 유효하지 않는 경우 발생 |
| EWB401 | 인증에 실패하였습니다. | 인증 서비스 권한이 없는 경우 발생 |
| EWB403 | 권한이 없습니다. | 해당 리소스에 대한 접근 권한이 없는 경우 발생 |
| EWB404 | 리소스를 찾을 수 없습니다. | 리소스가 존재하지 않을 때 발생 |
| EWB500 | 서버 내부 오류가 발생하였습니다. | 시스템 장애로 통신이 원활하지 않을 때 발생 |
| ACCESS_TOKEN_EXPIRED | access 토큰이 만료됨 | 만료된 access 토큰을 사용하고 있습니다. |
| REFRESH_TOKEN_EXPIRED | refresh 토큰이 만료됨 | 만료된 refresh 토큰을 사용하고 있습니다. |
| INVALID_TOKEN | 유효하지 않은 토큰 | 잘못된 형식의 토큰이 사용되었습니다. |
| MISSING_COOKIE | 쿠키가 존재하지 않음 | 요청에 필수 쿠키가 포함되지 않았습니다. |
| BAD_CREDENTIALS | 잘못된 자격 증명 | 제공된 자격 증명이 잘못되었습니다. |
| INVALID_AUTHORIZATION_HEADER | 인증 헤더가 잘못됨 | 인증 헤더가 잘못된 형식입니다. |
| INFRASTRUCTURE_ERROR | 외부 호출 오류 | 외부 서비스 호출에 문제가 발생하였습니다. |
| INTERNAL_SERVER_ERROR | 서버 내부 오류 | 서버 내부에서 예상치 못한 오류가 발생하였습니다. |
| USER_NOT_FOUND | 유저를 찾을 수 없음 | 요청된 유저가 존재하지 않습니다. |
EWB API는 공통된 에러 응답을 사용합니다. 아래는 응답 JSON 예시입니다.
{
"code": "ACCESS_TOKEN_EXPIRED",
"message": "토큰이 만료되었습니다.",
"status": 401
}
/v1 으로 시작하는 엔드포인트 /admin/v1으로 경로 변경 (File API, WorkBook API)어드민 사용자의 리프레시 토큰을 이용하여 새로운 액세스 토큰을 생성합니다. 사용자는 리프레시 토큰을 Authorization 헤더에 'Bearer {token}' 형식으로 제공하며, API는 새로운 액세스 토큰을 반환합니다.
| Authorization | string |
Authorization Header가 잘못되었을 때 발생합니다.
{- "code": 401,
- "description": "인증 헤더가 잘못됨",
- "errorCode": "INVALID_AUTHORIZATION_HEADER",
- "message": "Authorization Header가 잘못되었을 때 발생합니다."
}어드민 사용자가 로그아웃을 요청할 때 사용됩니다. 사용자는 로그인 시 받은 액세스 토큰을 Authorization 헤더에 'Bearer {token}' 형식으로 제공해야 합니다.
| Authorization | string |
Authorization Header가 잘못되었을 때 발생합니다.
{- "code": 401,
- "description": "인증 헤더가 잘못됨",
- "errorCode": "INVALID_AUTHORIZATION_HEADER",
- "message": "Authorization Header가 잘못되었을 때 발생합니다."
}어드민 사용자의 로그인 요청을 처리합니다. 사용자는 유효한 아이디와 비밀번호를 제공해야 하며, 성공적인 인증 후 JWT 토큰을 반환받습니다. 이 토큰은 다른 어드민 API 요청에 사용됩니다.
| username required | string 어드민 사용자 아이디 |
| password required | string 어드민 사용자 비밀번호 |
{- "username": "string",
- "password": "string"
}아이디 또는 비밀번호가 잘못되었을 때 발생합니다.
{- "code": 401,
- "description": "잘못된 자격 증명",
- "errorCode": "BAD_CREDENTIALS",
- "message": "아이디 또는 비밀번호가 잘못되었을 때 발생합니다."
}모의고사/수능 워크북을 수정합니다. 수정 가능한 항목은 다음과 같습니다.
요청 정보는 다음과 같습니다.
이 API는 PATCH 메서드를 사용하지만, sentences 필드에 대해서는 특별한 처리 방식을 사용합니다:
| passageId required | integer <int64> |
| subject | string or null 주제 |
| summary | string or null 요약 |
Array of objects or null or null (SentenceRequest) 문장 목록 |
{- "subject": "string",
- "summary": "string",
- "sentences": [
- {
- "content": "string",
- "translation": "string"
}
]
}| productId required | integer <int64> |
| name required | string 상품 이름 |
| examGrade required | integer <int32> 시행 학년 |
| examDay required | string <date> 실제 시험 날짜 |
| displayStatus required | string Enum: "DISPLAY_PENDING" "DISPLAY" 상품 상태 |
| thumbnailImage required | string <binary> |
| workbookFile required | string <binary> |
OAuth2 로그인 API입니다.
현재 지원하는 OAuth2 Provider(registrationId)는 kakao입니다. oauth2/authorization/{registrationId} 로 GET 요청을 보내면 OAuth2 로그인 페이지로 리다이렉트 됩니다.
OAuth2 인증 후 사용자를 리디렉션할 호스트 정보를 전달하기 위해, 요청 시 쿼리 파라미터로 host 값을 포함해야 합니다. 이를 통해 애플리케이션은 인증이 완료된 후 사용자를 적절한 클라이언트 애플리케이션으로 리다이렉트할 수 있습니다.
OAuth2 로그인 과정은 다음과 같습니다.
- 사용자가 /oauth2/authorization/{registrationId}로 GET 요청을 보내면, 해당 OAuth2 Provider의 로그인 페이지로 리다이렉트됩니다.
- 사용자가 OAuth2 Provider에서 인증을 완료하면, 해당 Provider는 인가 코드(Authorization Code)를 애플리케이션에 전달합니다.
- 애플리케이션은 받은 인가 코드를 사용하여 OAuth2 Provider로부터 액세스 토큰(Access Token)을 요청합니다.
- OAuth2 Provider는 액세스 토큰을 애플리케이션에 반환합니다.
- 애플리케이션은 받은 액세스 토큰을 사용하여, 애플리케이션에서 사용할 자체 액세스 토큰과 리프레시 토큰을 생성합니다.
- 생성된 액세스 토큰은 클라이언트와의 인증을 위해 사용되며, 리프레시 토큰은 액세스 토큰 갱신 시 사용됩니다.
모의고사/수능 워크북 상품 목록을 조회합니다.
해당 API는 인증이 필요하지 않습니다. 워크북 파일을 다운로드 받을 때 사용자 인증이 필요합니다.
| page | string <integer> Default: "0" Example: page=0 페이지 번호 첫번째 페이지 번호는 0부터 시작합니다. |
| size | string <integer> [ 1 .. 100 ] Default: "20" Example: size=20 페이지 크기 한 페이지에 조회할 항목의 갯수를 설정합니다. 최대 100개의 항목을 한번에 조회가능합니다. |
| year | string |
| grade | integer <int32> |
| months | Array of strings Items Enum: "JANUARY" "FEBRUARY" "MARCH" "APRIL" "MAY" "JUNE" "JULY" "AUGUST" "SEPTEMBER" "OCTOBER" "NOVEMBER" "DECEMBER" |