Skip to content

Latest commit

 

History

History
321 lines (178 loc) · 10.9 KB

API.md

File metadata and controls

321 lines (178 loc) · 10.9 KB

playlist-maker API

pl-maker의 API의 명세를 작성한 문서입니다. 조건, 참고사항, 예외 등을 명시합니다.

리소스

사용자 (users)

  • userId: 사용자의 고유 번호입니다. 가입한 순서대로 번호를 부여받는 4바이트 정수입니다.
  • username: 사용자의 이름입니다. 중복될 수 있는 길이 64 이하의 문자열입니다.
  • playlists: 사용자가 만든 플레이리스트의 목록입니다.
  • tags: 사용자가 노래에 붙인 태그의 목록입니다.

노래 (music)

  • musicId: 노래의 고유 번호입니다. 생성된 순서대로 번호를 부여받는 4바이트 정수입니다.
  • ytVideoId: 대응되는 유튜브 비디오 id입니다. 'A-Za-z0-9_-'로 이루어진 11글자 문자열입니다.
  • title: 노래의 제목입니다. 길이 255 이하의 문자열입니다.
  • thumbnailPath: 노래의 유튜브 썸네일 경로입니다. 추후에 이미지를 저장하는 방식이 변경될 수 있습니다.
  • playlistitems: 노래를 포함하는 플레이리스트 아이템의 목록입니다.
  • tags: 노래에 붙은 태그의 목록입니다.

플레이리스트 (playlists)

  • playlistId: 플레이리스트의 고유 번호입니다. 생성된 순서대로 번호를 부여받는 4바이트 정수입니다.
  • ytPlaylistId: 대응되는 유튜브 플레이리스트 id입니다. 길이 255 이하의 고유한 문자열입니다.
  • description: 플레이리스트의 설명입니다. 길이 512 이하의 문자열입니다.
  • user: 플레이리스트를 만든 사용자입니다.
  • playlistitems: 플레이리스트를 포함하는 플레이리스트 아이템의 목록입니다.

플레이리스트 아이템 (playlistitems)

  • playlistitemId: 플레이리스트 아이템의 고유 번호입니다. 생성된 순서대로 번호를 부여받는 4바이트 정수입니다.
    • 특정 노래가 특정 플레이리스트에 포함되어 있음을 나타냅니다.
    • (music, playlist)는 고유하지 않습니다. 하나의 플레이리스트에 같은 노래가 2개 이상 포함될 수 있습니다.
  • ytPlaylistitemId: 대응되는 유튜브 플레이리스트 아이템의 id입니다. 길이 255 이하의 고유한 문자열입니다.
  • music: 플레이리스트 아이템의 노래입니다.
  • playlist: 플레이리스트 아이템의 플레이리스트입니다.

태그 (tags)

검색 기능 스펙이 확정되지 않아 변경될 가능성이 큽니다.

  • tagId: 태그의 고유 번호입니다. 생성된 순서대로 번호를 부여받는 4바이트 정수입니다.
    • (key, value) 형태로 구성됩니다. (userId, musicId)마다 key는 unique합니다.
  • tagName: 태그의 이름입니다.
  • valueType: 태그의 값의 타입입니다. 'number' 혹은 'string'입니다. 유효한 타입이 추가될 수 있습니다.
  • intValue: 태그의 값입니다. valueType이 'number'가 아닐 경우 null입니다. 4바이트 정수입니다.
  • strValue: 태그의 값입니다. valueType이 'string'이 아닐 경우 null입니다. 길이 255 이하의 문자열입니다.
  • user: 태그를 붙인 사용자입니다.
  • music: 태그가 붙은 노래입니다.

API 엔드포인트

사용자의 입력은 (1) Path Variable, (2) Query String, (3) Body 중 한 가지 형식으로 들어옵니다.

  • Path Variable 입력은 GET /music/:id처럼 콜론을 이용해 표기합니다.
    • :id로 표기된 Path Variable은 해당 pl-maker 리소스의 고유 번호를 의미합니다.
  • Query String과 Body 입력은 API 동작 설명 직후에 명시합니다.

별도 언급이 없는 경우, 추가적인 입력이 없음을 의미합니다. 세션 ID 입력은 별도로 표기하지 않습니다.

성공 시 응답의 상태 코드는 200이고 JSON 객체를 반환합니다. 반환값은 다음과 같이 설명합니다.

  • { musicId, ytVideoId, title }
    • ytVideoId: 유튜브 비디오 id입니다. 'A-Za-z0-9_-'로 이루어진 11글자 문자열입니다.

실제 반환값의 예시로는 { "musicId": 1, "ytVideoId": "VNY5H-ttGgw", title: "높은 마음" }이 가능합니다.

실패 시 처리를 상태 코드 별로 설명합니다. 반환값은 { statusCode, message, path } 꼴의 JSON 객체입니다.

  • message: 실패 메시지입니다.
  • path: 실패한 요청의 URL입니다.

실제 반환값의 예시로는 { "statusCode": 404, "message": "Music Not Found", "path": "/music/2" }이 가능합니다.

404와 같이 취소줄이 그어져있는 경우 미구현 혹은 스펙 미정을 의미합니다.

POST /auth/login

로그인을 위해 구글 인증 페이지로 리다이렉트합니다.

성공 시 응답은 다음과 같습니다.

  • 상태 코드: 302 Found
  • 헤더
    • Location: redirect_uri
    • Content-Length: 0

POST /auth/logout

사용자를 로그아웃시킵니다. 요청에 포함된 세션 ID를 삭제합니다.

성공 시 반환값은 JSON이며, 빈 객체입니다.

실패 시 처리는 다음과 같습니다.

  • 401: 로그인을 하지 않은 경우입니다.

GET /users/me

요청한 사용자의 정보를 반환합니다.

성공 시 반환값은 JSON이며, 다음과 같은 객체입니다.

  • { userId, username, googleSub }
    • googleSub: 구글 계정을 식별하는 고유한 id입니다.

실패 시 처리는 다음과 같습니다.

  • 401: 로그인을 하지 않은 경우입니다.

GET /users/:id

해당 사용자를 반환합니다.

성공 시 반환값은 JSON이며, 다음과 같은 객체입니다.

  • { userId, username, googleSub }
    • googleSub: 구글 계정을 식별하는 고유한 id입니다.

실패 시 처리는 다음과 같습니다.

  • 401: 로그인을 하지 않은 경우입니다.
  • 403: 요청한 사용자가 해당 사용자를 볼 권한이 없는 경우입니다.
  • 404: 찾으려는 사용자가 존재하지 않는 경우입니다.

DELETE /users/:id

해당 사용자를 삭제합니다.

GET /music/:id

해당 노래를 반환합니다.

성공 시 반환값은 JSON이며, 다음과 같은 객체입니다.

  • { musicId, ytVideoId, title, thumbnailPath }

실패 시 처리는 다음과 같습니다.

  • 404: 해당 노래가 존재하지 않는 경우입니다.

GET /music

모든 노래의 목록을 반환합니다. 주어진 조건에 맞는 노래의 목록을 반환합니다.

  • query: 노래 검색 쿼리입니다.
  • sort: 노래를 정렬할 기준입니다.
  • page: 페이지의 번호입니다.

성공 시 반환값은 JSON이며, 다음과 같은 객체입니다.

  • [ { musicId, ytVideoId, title, thumbnailPath }, ... ]

POST /music

노래를 새로 추가합니다.

  • { ytVideoId }

성공 시 반환값은 JSON이며, 다음과 같은 객체입니다.

  • { musicId, ytVideoId, title, thumbnailPath }

실패 시 처리는 다음과 같습니다.

  • 401: 로그인을 하지 않은 경우입니다.
  • 403: 요청한 사용자가 노래를 추가할 권한이 없는 경우입니다.
  • 409: 해당 ytVideoId 노래가 이미 있는 경우입니다.

POST /playlists

플레이리스트를 새로 생성합니다. 해당 사용자의 유튜브 계정에서도 플레이리스트를 생성해야 합니다.

  • { title?, description? }

성공 시 반환값은 JSON이며, 다음과 같은 객체입니다.

  • { playlistId, ytPlaylistId, title, description }

실패 시 처리는 다음과 같습니다.

  • 401: 로그인을 하지 않은 경우입니다.

GET /playlists

요청한 사용자의 모든 플레이리스트의 목록을 반환합니다.

  • sort: 플레이리스트를 정렬할 기준입니다.
  • page: 페이지의 번호입니다.

성공 시 반환값은 JSON이며, 다음과 같은 객체입니다.

  • [ { playlistId, ytPlaylistId, title, description }, ... ]

실패 시 처리는 다음과 같습니다.

  • 401: 로그인을 하지 않은 경우입니다.

GET playlists/:id

해당 플레이리스트를 반환합니다.

성공 시 반환값은 JSON이며, 다음과 같은 객체입니다.

  • { playlistId, ytPlaylistId, title, description }

실패 시 처리는 다음과 같습니다.

  • 401: 로그인을 하지 않은 경우입니다.
  • 403: 요청한 사용자가 해당 플레이리스트를 읽을 권한이 없는 경우입니다.
  • 404: 해당 플레이리스트가 존재하지 않는 경우입니다.

PATCH /playlists/:id

해당 플레이리스트를 수정합니다.

성공 시 반환값은 JSON이며, 다음과 같은 객체입니다.

  • { playlistId, ytPlaylistId, title, description }

실패 시 처리는 다음과 같습니다.

  • 401: 로그인을 하지 않은 경우입니다.
  • 403: 요청한 사용자가 해당 플레이리스트를 수정할 권한이 없는 경우입니다.
  • 404: 해당 플레이리스트가 존재하지 않는 경우입니다.

DELETE /playlists/:id

해당 플레이리스트를 삭제합니다.

성공 시 반환값은 JSON이며, 빈 객체입니다.

실패 시 처리는 다음과 같습니다.

  • 401: 로그인을 하지 않은 경우입니다.
  • 403: 요청한 사용자가 해당 플레이리스트를 삭제할 권한이 없는 경우입니다.
  • 404: 해당 플레이리스트가 존재하지 않는 경우입니다.

GET /tags

요청한 사용자의 주어진 조건을 만족하는 태그의 목록을 반환합니다.

  • musicId: 해당 노래에 붙은 태그들만 검색합니다.
  • sort
  • page

성공 시 반환값은 JSON이며, 다음과 같은 객체입니다.

  • [{ ? }]

실패 시 처리는 다음과 같습니다.

  • 400: 쿼리 스트링에 musicId가 포함되지 않은 경우입니다.
  • 401: 로그인을 하지 않은 경우입니다.

POST /tags

태그를 새로 추가합니다.

  • { musicId, tagName, valueType, value }

성공 시 반환값은 JSON이며, 다음과 같은 객체입니다.

  • { ? }

실패 시 처리는 다음과 같습니다.

  • 401: 로그인을 하지 않은 경우입니다.
  • 404: muscId에 해당하는 노래가 없는 경우입니다.
  • 409: 요청한 사용자가 이미 해당 노래에 tagName의 태그를 붙인 경우입니다.

PATCH /tags/:id

해당 태그를 수정합니다.

  • { musicId, tagName, valueType, value }

성공 시 반환값은 JSON이며, 다음과 같은 객체입니다.

  • { ? }

실패 시 처리는 다음과 같습니다.

  • 400: 요청 Body가 잘못된 경우입니다.
    • 태그의 musicId가 변경되는 경우가 해당됩니다.
  • 401: 로그인을 하지 않은 경우입니다.
  • 403: 요청한 사용자가 해당 태그를 수정할 권한이 없는 경우입니다.

DELETE /tags/:id

해당 태그를 삭제합니다.

성공 시 반환값은 JSON이며, 빈 객체입니다.

실패 시 처리는 다음과 같습니다.

  • 401: 로그인을 하지 않은 경우입니다.
  • 403: 요청한 사용자가 해당 태그를 삭제할 권한이 없는 경우입니다.