Folders API

폴더를 다루는 API입니다. 폴더와 파일에 공통으로 적용되는 리소스 모델, 목록 조회, 폴더 트리는 Common conventions에서 설명합니다. 이 페이지에서는 폴더에만 해당하는 기능을 설명합니다.

Base URL과 scope

/api/external/v1/folders

읽기 기능에는 api:read가 필요합니다. 업로드·삭제·이름 변경·이동에는 api:write도 함께 필요합니다.

권한 검사

다른 사용자의 폴더를 다룰 때는 기능별로 해당 사용자가 부여한 권한을 검사합니다.

기능	검사하는 권한
업로드	대상 위치 폴더의 UPLOAD
이름 변경	대상 폴더의 EDIT
이동	대상 위치 폴더의 UPLOAD와 이동할 폴더의 EDIT
다운로드	대상 폴더의 DOWNLOAD

공유받지 않은 폴더는 PERMISSION_001로, 권한이 없으면 PERMISSION_002로 실패합니다.

폴더 업로드

api:write 필요

POST /api/external/v1/folders

파라미터	Type	필수	설명
fn	string	Yes	폴더 이름. 최대 255자
pfs	long	No	부모 폴더 seq. ss를 보낼 때 필수
ss	integer	No	공유 사용자 seq

Create folder

curl -X POST "https://drive.example.com/api/external/v1/folders" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"pfs": 5, "fn": "Contracts"}'

Create folder response

{
  "result": true,
  "code": 201,
  "message": "Created",
  "data": {
    "resourceSeq": 2056,
    "resourceName": "Contracts"
  }
}

pfs를 생략하면 드라이브 최상위에 폴더를 만듭니다. 같은 부모 폴더에 같은 이름의 폴더가 있으면 오류 없이 번호를 붙인 이름으로 만듭니다. 실제로 생성된 이름은 응답의 resourceName에서 확인하세요. 생성하기 전에 이름 중복 여부를 확인하려면 Common conventions의 이름 중복 확인 endpoint를 사용하세요.

폴더 이름 변경

api:write 필요

PATCH /api/external/v1/folders/{resourceSeq}/rename

파라미터	Type	필수	설명
resourceSeq	long	Yes	path 파라미터 - 이름을 바꿀 폴더
rn	string	Yes	새 이름. 최대 255자
ss	integer	No	공유 사용자 seq. 공유 폴더면 필수
pfs	long	No	부모 폴더 seq. 공유 여부와 관계없이 최상위 폴더가 아니면 필수

Rename folder

curl -X PATCH "https://drive.example.com/api/external/v1/folders/{resourceSeq}/rename" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"ss": 21, "pfs": 5, "rn": "Signed contracts"}'

pfs는 이름 중복을 검사할 부모 폴더입니다. 생략하면 드라이브 최상위를 기준으로 검사합니다.

업로드와 달리 이름을 변경할 때는 중복된 이름에 번호를 붙이지 않습니다. 같은 부모 폴더에 같은 이름의 폴더가 있으면 RESOURCE_006(409)으로 실패합니다. 파일 이름 변경 endpoint와 달리 이름 중복 처리 방식을 지정하는 파라미터가 없습니다.

Rename folder failure

{
  "result": false,
  "code": 409,
  "errorCode": "RESOURCE_006",
  "message": "..."
}

폴더 이동

api:write 필요

POST /api/external/v1/folders/{resourceSeq}/move

파라미터	Type	필수	설명
resourceSeq	long	Yes	path 파라미터 - 이동할 폴더
ts	integer	No	대상 사용자 seq. 다른 사용자의 폴더로 옮길 때 필수. 생략하면 본인
pfs	long	No	이동할 위치(새 부모 폴더)의 seq. ts가 본인이 아니면 필수. 생략하면 최상위로 이동
ss	integer	No	공유 사용자 seq

Move folder

curl -X POST "https://drive.example.com/api/external/v1/folders/{resourceSeq}/move" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"ts": 1, "ss": 21, "pfs": 5}'

폴더를 이동하면 하위 파일과 폴더도 함께 이동합니다. 폴더 자신의 하위 폴더나 현재 부모 폴더로는 이동할 수 없으며, 이 경우 RESOURCE_002로 실패합니다. 잠긴 폴더는 RESOURCE_LOCK_ASPECT_002(423)로 실패합니다.

Move folder failure

{
  "result": false,
  "code": 400,
  "errorCode": "RESOURCE_002",
  "message": "..."
}

폴더 삭제

api:write 필요

PATCH /api/external/v1/folders/{resourceSeq}/delete

파라미터	Type	필수	설명
resourceSeq	long	Yes	path 파라미터 - 삭제할 폴더

삭제한 폴더와 하위 파일·폴더는 바로 제거되지 않고 휴지통으로 이동합니다. 삭제에 실패하면 RESOURCE_001을 반환합니다.

본인 소유 폴더만 삭제할 수 있으므로 ss 파라미터가 없습니다. 공유받은 폴더는 RESOURCE_005로, 잠긴 폴더는 RESOURCE_LOCK_ASPECT_002(423)로 실패합니다.

Delete folder failure

{
  "result": false,
  "code": 423,
  "errorCode": "RESOURCE_LOCK_ASPECT_002",
  "message": "..."
}

폴더 다운로드

폴더는 두 단계를 거쳐 ZIP 파일로 내려받습니다. 먼저 API Key로 다운로드 토큰을 발급받습니다.

GET /api/external/v1/folders/{resourceSeq}/download-token

Header	필수	값
Authorization	Yes	Bearer 뒤에 API Key

파라미터	Type	필수	설명
resourceSeq	long	Yes	path 파라미터 - 내려받을 폴더
ss	integer	No	공유 사용자 seq

Issue folder download token

curl "https://drive.example.com/api/external/v1/folders/{resourceSeq}/download-token" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY"

Folder token response

{
  "result": true,
  "code": 200,
  "message": "OK",
  "data": {
    "linkUrl": "/folders/download?dt={token}"
  }
}

linkUrl은 상대 경로입니다. 사용자가 접속한 Drive 호스트를 앞에 붙여 브라우저에서 엽니다. 예를 들면 https://drive.example.com/folders/download?dt={dt}입니다. 이 브라우저 요청에는 API Key가 필요하지 않습니다. /api/external/v1/folders/download는 직접 호출하지 마세요. 이 경로는 API Key를 bearer token으로 요구하므로 브라우저에서 다운로드할 때는 사용할 수 없습니다.

GET /folders/download?dt={dt}

공통 JSON 구조 대신 ZIP 파일을 스트림으로 반환합니다.

HTTP 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="archive.zip"

고정 폴더

사용자는 자주 사용하는 폴더를 고정해 빠르게 접근할 수 있습니다. 고정 폴더는 사용자별로 관리하며 최대 3개까지 등록할 수 있습니다.

고정 폴더는 api:read로 변경 가능

고정 폴더 등록과 해제는 쓰기 기능으로 분류되지 않습니다. api:read만 부여된 키로도 고정 폴더 목록을 변경할 수 있습니다.

고정 폴더 목록

GET /api/external/v1/pinned-folders

파라미터가 없습니다. 결과는 고정한 순서대로 정렬됩니다. 원본 폴더가 삭제되면 목록에서 자동으로 제외됩니다.

Field	Type	의미
pinnedFolderSeq	long	고정 폴더 항목의 식별자. 고정을 해제할 때 사용
resourceSeq	long	고정된 폴더
sharedByUserSeq	integer	폴더 소유자의 사용자 seq. 본인 폴더면 본인 seq
resourceName	string	폴더 이름
resourceType	enum	항상 FOLDER

폴더 고정

POST /api/external/v1/pinned-folders

파라미터	Type	필수	설명
rs	long	Yes	폴더 리소스 seq. 파일 seq를 보내면 RESOURCE_005로 실패
ss	integer	No	폴더 소유자의 사용자 seq. 공유받은 폴더를 고정할 때 필수

Pin folder

curl -X POST "https://drive.example.com/api/external/v1/pinned-folders" \
  -H "Authorization: Bearer replace-with-your-USER-API-KEY" \
  -H "Content-Type: application/json" \
  -d '{"rs": 17466, "ss": 43}'

폴더의 보기 권한을 검사합니다. 공유받지 않은 폴더는 PERMISSION_001로, 접근할 수 없는 폴더는 PERMISSION_002로 실패합니다. 이미 고정한 폴더를 다시 고정하면 PINNED_FOLDER_002로, 3개를 초과하면 PINNED_FOLDER_003으로 실패합니다.

고정 해제

DELETE /api/external/v1/pinned-folders/{pinnedFolderSeq}

파라미터	Type	필수	설명
pinnedFolderSeq	long	Yes	path 파라미터 - 고정을 해제할 항목

본인이 고정한 항목이 아니거나 이미 해제된 항목을 지정하면 PINNED_FOLDER_001을 반환합니다. 고정을 해제해도 폴더는 삭제되지 않습니다.

오류

요청이 실패하면 공통 실패 구조로 응답합니다.

Failure envelope

{
  "result": false,
  "code": 400,
  "errorCode": "REQUEST_001",
  "message": "..."
}

errorCode	HTTP	의미
REQUEST_001	400	요청 값 검증 실패
RESOURCE_001	400	삭제 실패
RESOURCE_002	400	이동 실패. 폴더 자신의 하위 폴더나 현재 부모 폴더로 이동하는 경우 포함
RESOURCE_005	404	리소스를 찾을 수 없음. 본인 소유가 아닌 폴더를 삭제하는 경우 포함
RESOURCE_006	409	부모 폴더에 새 이름과 같은 폴더가 있음
PERMISSION_001	403	공유받지 않은 폴더
PERMISSION_002	403	폴더에 대한 권한 없음
RESOURCE_LOCK_ASPECT_002	423	잠긴 폴더
AUTH_009	403	API Key가 유효하지 않거나 필요한 scope가 없음
RESPONSE_001	500	서버 오류

API 전체에 공통으로 사용하는 오류 코드는 Errors를 참고하세요.