Skip to content

3.Backend-REST-API.md

Latest commit

 

History

History
1107 lines (768 loc) · 41 KB

3.Backend-REST-API.md

File metadata and controls

1107 lines (768 loc) · 41 KB

Media Streaming Backend REST API Reference

1. 유저 API

1.1 회원가입

새로운 사용자를 생성합니다.

ID URL HOST METHOD
US01-1 /users/signup http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Request Body
Name Type Description Required
username String 사용자 이름 TRUE
password String 비밀번호 TRUE
email String 사용자 이메일 TRUE
Response
Status Code Description
201 성공
Name Type Description
message String 회원가입 성공 메시지

1.2 로그인

사용자의 로그인 상태를 확인하고 토큰을 발급합니다.

ID URL HOST METHOD
US01-2 /users/login http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Request Body
Name Type Description Required
email String 사용자 이메일 TRUE
password String 비밀번호 TRUE
Response
Status Code Description
200 성공
Name Type Description
id Number 사용자 ID
username String 사용자 이름
email String 사용자 이메일
accountType String 계정 유형
role String 사용자 권한

1.3 로그아웃

사용자의 로그인 상태를 종료하고 로그아웃 처리합니다.

ID URL HOST METHOD
US01-3 /users/logout http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Response
Status Code Description
200 성공
Name Type Description
message String 로그아웃 완료 메시지

1.4 현재 사용자 정보 조회

현재 로그인한 사용자의 정보를 조회합니다.

ID URL HOST METHOD
US01-4 /users/me http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com GET
Response
Status Code Description
200 성공
Name Type Description
id Number 사용자 ID
username String 사용자 이름
email String 사용자 이메일
accountType String 계정 유형
role String 사용자 권한

1.5 사용자 토큰 인증 확인

JWT 토큰의 유효성을 확인합니다.

ID URL HOST METHOD
US01-4 /users/auth http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com GET
Response
Status Code Description
200 유효 토큰
401 유효하지 않은 토큰

2. 미디어 관리 API

2.1 미디어 목록 조회

미디어 목록을 페이징으로 조회하며 태그 또는 제목+내용 검색 기능을 지원합니다.

ID URL HOST METHOD
MD01-1 /media http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com GET
Request Parameter
Name Type Description Required
page String 페이지 번호 (0부터 시작) FALSE
size String 페이지 크기 FALSE
sort String 정렬 기준 (e.g., view,desc) FALSE
searchTags String 태그 검색 여부 (true/false) FALSE
keywords String 검색 키워드 (여러 개 가능) FALSE
Response
Status Code Description
200 성공
Name Type Description
content Array 미디어 목록
- id Number 미디어 ID
- title String 미디어 제목
- duration Number 동영상 길이 (초 단위)
- thumbnail String 썸네일 URL
- view Number 조회수
- userId Number 작성자 ID
- userName String 작성자 이름
- userType String 작성자 유형 (black/white)
number Number 현재 페이지 번호
size Number 페이지 크기
totalPages Number 전체 페이지 수
totalElements Number 총 요소 수

2.2 미디어 게시글 생성

업로드된 영상을 공개하여 게시글을 생성합니다.

ID URL HOST METHOD
MD02-1 /media http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Request Body
Name Type Description Required
title String 미디어 제목 TRUE
description String 미디어 설명 TRUE
tags String[] 미디어 태그 FALSE
stoppoints Array 정지점 리스트 FALSE
- stop_time Number 정지점 시간 (초 단위) TRUE
- description String 정지점 설명 TRUE
Response
Status Code Description
200 성공
Name Type Description
id Number 생성된 미디어 ID
title String 미디어 제목
description String 미디어 설명
duration Number 동영상 길이 (초 단위)
videoUrl String 동영상 URL
thumbnailUrl String 썸네일 URL
tags String[] 미디어 태그
createdAt String 생성일
updatedAt String 수정일
view Number 조회수
userId Number 작성자 ID
userName String 작성자 이름
userType String 작성자 유형 (black/white)

2.3 내가 업로드한 영상 목록 조회

현재 로그인한 사용자가 업로드한 영상 목록을 조회합니다.

ID URL HOST METHOD
MD01-2 /media/me http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com GET
Request Parameter
Name Type Description Required
page String 페이지 번호 (0부터 시작) FALSE
size String 페이지 크기 FALSE
sort String 정렬 기준 FALSE
Response
Status Code Description
200 성공
Name Type Description
content Array 사용자가 업로드한 미디어 목록
- id Number 미디어 ID
- title String 미디어 제목
- duration Number 동영상 길이 (초 단위)
- thumbnail String 썸네일 URL
- view Number 조회수
- createdAt String 생성일
number Number 현재 페이지 번호
size Number 페이지 크기
totalPages Number 전체 페이지 수
totalElements Number 총 요소 수

2.4 미디어 퀄리티 데이터 저장

미디어 품질 데이터를 저장합니다.

ID URL HOST METHOD
MD01-3 /media/quality-stats http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Request Body
Name Type Description Required
mediaId Number 미디어 ID TRUE
userId Number 사용자 ID TRUE
downloadBitrate Number 다운로드 비트레이트 TRUE
selectedBitrate Number 선택된 비트레이트 TRUE
bufferingStart Number 버퍼링 시작 시간 (초) TRUE
bufferingEnd Number 버퍼링 종료 시간 (초) TRUE
Response
Status Code Description
200 성공

2.5 특정 미디어 상세 조회

특정 미디어 ID를 통해 상세 정보를 조회합니다.

ID URL HOST METHOD
MD03-1 /media/{id} http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com GET
Request Parameter
Name Type Description Required
id String 조회할 미디어 ID TRUE
Response
Status Code Description
200 성공
Name Type Description
id Number 미디어 ID
title String 미디어 제목
description String 미디어 설명
duration Number 동영상 길이 (초 단위)
videoUrl String 동영상 URL
thumbnailUrl String 썸네일 URL
tags String[] 미디어 태그
createdAt String 생성일
updatedAt String 수정일
view Number 조회수
userId Number 작성자 ID
userName String 작성자 이름
userType String 작성자 유형 (black/white)

2.6 미디어 댓글 목록 조회

특정 미디어에 작성된 댓글 목록을 조회합니다.

ID URL HOST METHOD
MD01-4 /media/{mediaId}/comments http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com GET
Request Parameter
Name Type Description Required
mediaId String 조회할 미디어 ID TRUE
Response
Status Code Description
200 성공
Name Type Description
content Object[] 댓글 목록
- id Number 댓글 ID
- content String 댓글 내용
- userId Number 댓글 작성자 ID
- username String 댓글 작성자 이름
- userType String 댓글 작성자 계정 유형
- mediaId Number 댓글이 작성된 미디어 ID
- replyCount Number 댓글에 달린 답글 수
number Number 현재 페이지 번호
size Number 페이지 크기
totalPages Number 총 페이지 수
totalElements Number 총 댓글 수

2.7 해당 미디어에 댓글 추가

특정 미디어에 댓글을 추가합니다.

ID URL HOST METHOD
MD09-1 /media/{mediaId}/comments http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Request Parameter
Name Type Description Required
mediaId String 댓글을 추가할 미디어 ID TRUE
Request Body
Name Type Description Required
content String 댓글 내용 TRUE
Response
Status Code Description
201 성공
Name Type Description
id Number 생성된 댓글 ID
content String 댓글 내용
userId Number 작성자 ID
username String 작성자 이름
userType String 작성자 유형 (black/white)
mediaId Number 댓글이 추가된 미디어 ID

2.8 미디어 좋아요 개수 조회

특정 미디어의 좋아요 개수를 조회합니다.

ID URL HOST METHOD
MD10-1 /media/{mediaId}/likes http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com GET
Request Parameter
Name Type Description Required
mediaId String 좋아요 개수를 조회할 미디어 ID TRUE
Response
Status Code Description
200 성공
Name Type Description
mediaId Number 미디어 ID
likeCount Number 좋아요 개수

2.9 미디어 좋아요 추가

특정 미디어에 좋아요를 추가합니다.

ID URL HOST METHOD
MD04-1 /media/{mediaId}/likes http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Request Parameter
Name Type Description Required
mediaId String 좋아요를 추가할 미디어 ID TRUE
Response
Status Code Description
201 성공

2.10 미디어 좋아요 삭제

특정 미디어에서 좋아요를 삭제합니다.

ID URL HOST METHOD
MD04-2 /media/{mediaId}/likes http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com DELETE
Request Parameter
Name Type Description Required
mediaId String 좋아요를 삭제할 미디어 ID TRUE
Response
Status Code Description
204 성공

2.11 미디어 정지점 목록 조회

특정 미디어의 정지점 목록을 조회합니다.

ID URL HOST METHOD
MD05-1 /media/{mediaId}/stoppoints http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com GET
Request Parameter
Name Type Description Required
mediaId String 조회할 미디어 ID TRUE
Response
Status Code Description
200 성공
Name Type Description
id Number 정지점 ID
stop_time Number 정지점 시간 (초)
description String 정지점 설명

2.12 미디어 정지점 생성

특정 미디어에 새로운 정지점을 생성합니다.

ID URL HOST METHOD
MD05-2 /media/{mediaId}/stoppoints http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Request Parameter
Name Type Description Required
mediaId String 정지점을 추가할 미디어 ID TRUE
Request Body
Name Type Description Required
stop_time Number 정지점 시간 (초 단위) TRUE
description String 정지점 설명 TRUE
Response
Status Code Description
201 성공
Name Type Description
id Number 정지점 ID
stop_time Number 정지점 시간 (초)
description String 정지점 설명

2.13 정지점 삭제

특정 미디어의 정지점을 삭제합니다.

ID URL HOST METHOD
MD05-3 /media/{mediaId}/stoppoints/{stoppointId} http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com DELETE
Request Parameter
Name Type Description Required
mediaId String 정지점을 삭제할 미디어 ID TRUE
stoppointId String 삭제할 정지점 ID TRUE
Response
Status Code Description
204 성공

3. 댓글 및 답글 관리 API

3.1 댓글 삭제

댓글 또는 답글을 삭제합니다.

ID URL HOST METHOD
CM01-1 /comments/{commentId} http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com DELETE
Request Parameter
Name Type Description Required
commentId String 삭제할 댓글 ID TRUE
Response
Status Code Description
204 성공

3.2 특정 댓글의 답글 조회

특정 상위 댓글의 답글 목록을 조회합니다.

ID URL HOST METHOD
CM01-2 /comments/{parentId}/replies http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com GET
Request Parameter
Name Type Description Required
parentId String 상위 댓글 ID TRUE
page String 페이지 번호 TRUE
size String 페이지 크기 TRUE
Response
Status Code Description
200 성공
Name Type Description
content Array 답글 목록
- id Number 답글 ID
- content String 답글 내용
- userId Number 답글 작성자 ID
- username String 답글 작성자 이름
- userType String 작성자 유형 (black/white)
- mediaId Number 연결된 미디어 ID

3.3 특정 댓글에 답글 추가

특정 상위 댓글에 답글을 추가합니다.

ID URL HOST METHOD
CM01-3 /comments/{parentId}/replies http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Request Parameter
Name Type Description Required
parentId String 답글 추가 대상 댓글 ID TRUE
Request Body
Name Type Description Required
content String 답글 내용 TRUE
Response
Status Code Description
201 성공
Name Type Description
id Number 답글 ID
content String 답글 내용
userId Number 답글 작성자 ID
username String 답글 작성자 이름
userType String 작성자 유형 (black/white)
mediaId Number 연결된 미디어 ID

4. 재생 기록 API

4.1 전체 재생 기록 조회

사용자의 모든 재생 기록을 조회합니다.

ID URL HOST METHOD
PL01-1 /playback/all http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com GET
Response
Status Code Description
200 성공
Name Type Description
mediaId Number 재생 기록이 있는 미디어 ID
mediaTitle String 미디어 제목
thumbnailUrl String 미디어 썸네일 URL
lastPlayedTime Number 마지막 재생 시간 (초 단위)
createdat String 재생 기록 생성 시간

4.2 재생 기록 삭제

특정 미디어의 재생 기록을 삭제합니다.

ID URL HOST METHOD
PL01-2 /playback/media/{mediaId} http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com DELETE
Request Parameter
Name Type Description Required
mediaId String 재생 기록을 삭제할 미디어 ID TRUE
Response
Status Code Description
204 성공

4.3 재생 기록 저장

특정 미디어의 재생 기록을 저장하거나 갱신합니다.

ID URL HOST METHOD
PL01-3 /playback/media/{mediaId} http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Request Parameter
Name Type Description Required
mediaId String 재생 기록을 저장할 미디어 ID TRUE
Request Body
Name Type Description Required
lastPlayedTime Number 마지막 재생 시간 (초 단위) TRUE
Response
Status Code Description
201 성공
Name Type Description
mediaId Number 재생 기록이 있는 미디어 ID
mediaTitle String 미디어 제목
thumbnailUrl String 미디어 썸네일 URL
lastPlayedTime Number 마지막 재생 시간 (초 단위)
createdat String 재생 기록 생성 시간

4.4 특정 사용자 재생 기록 삭제

사용자의 모든 재생 기록을 삭제합니다.

ID URL HOST METHOD
PL01-4 /playback/all http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com DELETE
Response
Status Code Description
200 성공

5. 재생 목록 API

5.1 사용자 재생목록 조회

사용자가 생성한 재생목록의 목록을 조회합니다.

ID URL HOST METHOD
MD03-1 /playlists http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com GET
Response
Status Code Description
200 성공
Name Type Description
content Object[] 재생목록 목록
- id Number 재생목록 ID
- title String 재생목록 제목
- description String 재생목록 설명
number Number 현재 페이지 번호
size Number 페이지 크기
totalPages Number 총 페이지 수
totalElements Number 총 재생목록 수

5.2 재생목록 생성

새로운 재생목록을 생성합니다.

ID URL HOST METHOD
MD03-2 /playlists http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Request Body
Name Type Description Required
title String 재생목록 제목 TRUE
description String 재생목록 설명 FALSE
Response
Status Code Description
201 성공
Name Type Description
id Number 생성된 재생목록 ID
title String 재생목록 제목
description String 재생목록 설명

5.3 재생목록 삭제

특정 재생목록을 삭제합니다.

ID URL HOST METHOD
MD03-3 /playlists/{playlistId} http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com DELETE
Request Parameter
Name Type Description Required
playlistId String 삭제할 재생목록 ID TRUE
Response
Status Code Description
204 성공

5.4 재생목록의 동영상 조회

특정 재생목록에 포함된 동영상 목록을 조회합니다.

ID URL HOST METHOD
MD03-4 /playlists/{playlistId}/items http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com GET
Request Parameter
Name Type Description Required
playlistId String 조회할 재생목록의 ID TRUE
Response
Status Code Description
200 성공
Name Type Description
content Object[] 재생목록 동영상 목록
- id Number 재생목록 아이템 ID
- playlistId Number 재생목록 ID
- mediaId Number 미디어 ID
- mediaTitle String 미디어 제목
- mediaThumbnailUrl String 미디어 썸네일 URL
- orderIndex Number 동영상 순서

5.5 재생목록에 동영상 추가

특정 재생목록에 동영상을 추가합니다.

ID URL HOST METHOD
MD03-5 /playlists/{playlistId}/items http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Request Parameter
Name Type Description Required
playlistId String 동영상을 추가할 재생목록 ID TRUE
Request Body
Name Type Description Required
mediaId Number 추가할 미디어 ID TRUE
orderIndex Number 동영상 추가 순서 TRUE
Response
Status Code Description
201 성공
Name Type Description
id Number 생성된 아이템 ID
playlistId Number 재생목록 ID
mediaId Number 미디어 ID
mediaTitle String 미디어 제목
mediaThumbnailUrl String 미디어 썸네일 URL
orderIndex Number 동영상 순서

5.6 재생목록 동영상 순서 변경

재생목록 내 동영상의 순서를 변경합니다.

ID URL HOST METHOD
MD03-6 /playlists/{playlistId}/items/order http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com PUT
Request Parameter
Name Type Description Required
playlistId String 순서를 변경할 재생목록 ID TRUE
Request Body
Name Type Description Required
mediaId Number 동영상 ID TRUE
orderIndex Number 변경할 동영상 순서 TRUE
Response
Status Code Description
200 성공

6. 랭킹 API

6.1 사용자 랭킹 조회

상위 20명의 사용자 랭킹 정보를 조회합니다.

ID URL HOST METHOD
MD04-1 /ranking/top20 http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com GET
Response
Status Code Description
200 성공
Name Type Description
userId Number 사용자 ID
username String 사용자 이름
score Number 사용자 점수

6.2 랭킹 수동 갱신

관리자가 랭킹 정보를 수동으로 갱신할 수 있습니다.

ID URL HOST METHOD
MD04-2 /ranking/update http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Response
Status Code Description
200 "Ranking updated successfully!"

7. 태그 API

7.1 태그 추천

동영상 업로드 시 추천 태그 목록을 제공합니다.

ID URL HOST METHOD
MD05-1 /tags/recommendation http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com GET
Response
Status Code Description
200 성공
Name Type Description
recommended_tags String[] 추천 태그 목록

8. 업로드 API

8.1 이미지 업로드

썸네일 이미지(jpg, 10mb 이하)을 업로드한 후, 업로드된 썸네일의 url을 반환한다.

ID URL HOST METHOD
MD07-1 /upload/image http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Request Body
Name Type Description Required
image File 업로드할 이미지 파일 (jpg) TRUE
Response
Status Code Description
200 성공
Name Type Description
thumbnailUrl String 업로드된 이미지의 URL

8.2 비디오 업로드 Presigned URL 생성

AWS S3에 비디오를 업로드하기 위한 presigned URL을 생성합니다.

ID URL HOST METHOD
MD07-2 /upload/video http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Request Body
Name Type Description Required
fileName String 업로드할 비디오 파일 이름 TRUE
fileSize Number 업로드할 비디오 파일 크기 (5MB~1GB) TRUE
key String 사용자 고유 키 TRUE
Response
Status Code Description
200 성공
Name Type Description
uploadId String Presigned URL 업로드 ID
url String[] Presigned URL 리스트
chunkSize Number 업로드할 비디오의 청크 크기

8.3 비디오 업로드 완료 처리

AWS S3 비디오 업로드가 완료되었음을 서버에 알립니다.

ID URL HOST METHOD
MD07-3 /upload/video/complete http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Request Body
Name Type Description Required
uploadId String 업로드한 Presigned URL의 ID TRUE
key String 사용자 고유 키 TRUE
results Object[] 업로드한 비디오 청크의 eTag 정보 TRUE
- partNumber Number 청크 번호 TRUE
- eTag String 업로드된 비디오 청크의 eTag TRUE
Response
Status Code Description
200 성공

8.4 사용자 업로드 고유키 생성

사용자가 영상을 업로드할 수 있는 10분 동안 유효한 고유키를 생성합니다.

ID URL HOST METHOD
MD12-1 /upload/video/generateKey http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com POST
Request Body

없음

Response
Status Code Description
200 성공
Name Type Description
key String 생성된 업로드 고유키

8.5 업로드된 비디오 처리 상태 조회

업로드된 비디오의 처리 상태를 조회합니다.

ID URL HOST METHOD
MD07-4 /upload/video/isProcessed http://ec2-43-202-184-195.ap-northeast-2.compute.amazonaws.com GET
Response
Status Code Description
200 성공
Name Type Description
fileName String 업로드된 비디오 파일 이름 (없으면 null)
isAvailable Boolean 비디오 처리 완료 여부
fileProcessState String 비디오 처리 상태 (UPLOADED, FINISH)
videoUrl String 비디오 URL (처리 완료된 경우)
duration Number 비디오 길이 (초 단위)
thumbnailUrl String 비디오 썸네일 URL