UPLOAD API

시스템 개요

Upload API는 파일을 CDN Storage에 upload, 조회, 삭제하는 기능을 지원합니다. Flow.js 기반의 청크 업로드와 다양한 파일 관리 기능을 REST API로 제공합니다.

기본 정보

서버	`fileupload.cdn.cloudn.co.kr`
URL 형식	`http://fileupload.cdn.cloudn.co.kr/[Method Name]`
지원 프로토콜	REST (HTTP POST / GET)
인증 방식	userid + passwd 또는 userid + auth_token (택1)

공통 인증 파라미터 (모든 API 공통)

Parameter	Required	Description	비고
userid	Y (필수)	FTP user id	ex) test
passwd	택1 필수	FTP user id password	passwd 또는 auth_token 중 1개 필수 선택
auth_token	택1 필수	FTP user id auth token (passwd 대신 사용 가능)	passwd 또는 auth_token 중 1개 필수 선택

API 목록

Method Name	HTTP Method	설명
upload	POST	파일을 CDN Storage에 Upload (Flow.js 청크 방식)
listup	POST	CDN Storage에서 주어진 경로에 대한 파일/디렉토리 조회
delete	POST	요청된 디렉토리/파일을 CDN Storage에서 삭제
extractzip	POST	Upload된 zip 파일을 압축 해제하여 같은 Directory에 저장
copy	POST	CDN Storage 상의 content를 복사
move	POST	CDN Storage 상의 content를 이동
mkdir	POST	CDN Storage 상에서 directory 생성
download	GET	CDN Storage 상의 content를 다운로드
uploadput	PUT	CDN Storage에 content upload (PUT method)
rename	POST	CDN Storage 상의 파일/디렉토리 rename

POST

Upload (flow.js)

http://fileupload.cdn.cloudn.co.kr/upload

※ Upload API는 Flow.js(https://github.com/flowjs/flow.js) open source를 이용. Client에서 Speedy에서 수정한 flow.js 파일을 이용하여 구현하여야 합니다.

Client는 Upload API 서버에 contents를 Upload하기 위해 Upload-Check를 요청한 후 chunk 단위로 multipart upload를 시작합니다.

공통 인증 파라미터

Parameter	Required	Description	비고
userid	Y	FTP user id	ex) test
passwd	택1	FTP user id password	passwd 또는 auth_token 중 1개 필수 ex) 1234
auth_token	택1	FTP user id auth token (passwd 대신 사용)	passwd 또는 auth_token 중 1개 필수 ex) 1234	ex) abc6e615-6f36-419a-b961-3a0df78f8a96

추가 파라미터

Parameter	Required	Description	비고
subpath	Y	Upload 할 FTP에서의 subpath	ex) testsubpath1/23/06/05
callback_url	선택	Upload 완료 후 호출할 callback url	ex) http://test.co.kr/uploadcompleted

Upload 완료 시 Callback 파라미터

Parameter	Description	비고
request_id	해당 파일의 upload request id	ex) 42a67530-3752-11e6-bfdd-71b7f85d5fc7
service	Upload Service ID (고정)	ex) NIM10001
title	Upload file Name	ex) 1.mp4

💡 Upload 완료 후 callback_url을 HTTP POST method로 호출하여 완료된 파일 정보를 JSON 형식으로 전달합니다.

Request Example (JSON Body)

Upload 요청

{ "userid": "test", "passwd": "1234", "subpath": "testsubpath1/23/06/05", "callback_url": "http://test.co.kr/uploadcompleted" } // auth_token 사용 시 { "userid": "test", "auth_token": "abc6e615-6f36-419a-b961-3a0df78f8a96", "subpath": "testsubpath1/23/06/05", "callback_url": "http://test.co.kr/uploadcompleted" }

Callback 수신 예시

{ "request_id": "42a67530-3752-11e6-bfdd-71b7f85d5fc7", "service": "NIM10001", "title": "1.mp4" }

POST

Listup — CDN Storage 조회

http://fileupload.cdn.cloudn.co.kr/listup

※ Content-Type: Application/json 헤더 필수

CDN Storage에 존재하는 파일/디렉토리 정보를 조회합니다. Directory인 경우 하위 모든 파일/디렉토리 정보를 제공합니다.

공통 인증 파라미터

Parameter	Required	Description	비고
userid	Y	FTP user id	ex) test
passwd	택1	FTP user id password	passwd 또는 auth_token 중 1개 필수 ex) 1234
auth_token	택1	FTP user id auth token (passwd 대신 사용)	passwd 또는 auth_token 중 1개 필수 ex) 1234	ex) abc6e615-6f36-419a-b961-3a0df78f8a96

추가 파라미터

Parameter	Required	Description	비고
path	Y	조회할 FTP에서의 path	ex) testsubpath1/23/06/05 또는 testsubpath55/15/07/23/2.mp4

응답 파라미터

Parameter	Description	비고
result_code	Result code	ex) 200, 401, 404, 500
result_msg	Result message	ex) success, not found
path	조회 대상이 된 path	ex) testsubpath1/23/06/05
list[].name	File 또는 Directory name	ex) 1.mp4
list[].type	Directory/File Type	F: file, D: directory
list[].last-modified	가장 최근 수정(생성) Date	형식: yyyyMMddHHmmss ex) 20230602153824
list[].size	File Size	ex) 110011072

Request Example

JSON Body

{ "userid": "test", "passwd": "1234", "path": "testsubpath1/23/06/05" }

Response (Directory 조회)

{ "result_code": "200", "result_msg": "success", "path": "testsubpath1/23/06/05", "list": [ { "name": "1.mp4", "type": "F", "last-modified": "20230602153824", "size": "110011072" }, { "name": "2.mp4", "type": "F", "last-modified": "20230610231219", "size": "265938726" }, { "name": "12", "type": "D", "last-modified": "20230617101135", "size": "4096" } ] }

POST

Delete — 경로 삭제

http://fileupload.cdn.cloudn.co.kr/delete

※ Content-Type: Application/json 헤더 필수

CDN Storage에 존재하는 파일/디렉토리를 삭제합니다. Directory인 경우 하위 모든 파일/디렉토리를 삭제합니다. ⚠️ 삭제는 매우 위험하니 신중하게 처리해야 합니다.

공통 인증 파라미터

Parameter	Required	Description	비고
userid	Y	FTP user id	ex) test
passwd	택1	FTP user id password	passwd 또는 auth_token 중 1개 필수 ex) 1234
auth_token	택1	FTP user id auth token (passwd 대신 사용)	passwd 또는 auth_token 중 1개 필수 ex) 1234	ex) abc6e615-6f36-419a-b961-3a0df78f8a96

추가 파라미터

Parameter	Required	Description	비고
path	Y	삭제할 FTP에서의 path	ex) testsubpath1/23/06/05 또는 testsubpath55/15/07/23/2.mp4

⚠️ Directory 삭제 시 하위 모든 파일과 디렉토리가 함께 삭제됩니다. 삭제된 파일은 복구가 불가능합니다.

응답 파라미터

Parameter	Description	비고
result_code	Result code	ex) 200, 401, 404, 500
result_msg	Result message	ex) success, not found
path	삭제 대상이 된 path

Request Example

JSON Body

// File 삭제 { "userid": "test", "passwd": "1234", "path": "testsubpath1/23/06/05/1.mp4" } // Directory 삭제 { "userid": "test", "auth_token": "abc6e615-6f36-419a-b961-3a0df78f8a96", "path": "testsubpath1/23/06/05" }

Response

{ "result_code": "200", "result_msg": "success", "path": "testsubpath1/23/06/05/1.mp4" }

POST

UnZIP — 압축 해제

http://fileupload.cdn.cloudn.co.kr/extractzip

※ Content-Type: Application/json 헤더 필수. 한 번에 하나의 zip 파일만 압축 해제합니다.

Upload된 *.zip 파일의 압축을 풀어 해당 zip 파일과 같은 경로상에 위치하게 합니다.

공통 인증 파라미터

Parameter	Required	Description	비고
userid	Y	FTP user id	ex) test
passwd	택1	FTP user id password	passwd 또는 auth_token 중 1개 필수 ex) 1234
auth_token	택1	FTP user id auth token (passwd 대신 사용)	passwd 또는 auth_token 중 1개 필수 ex) 1234	ex) abc6e615-6f36-419a-b961-3a0df78f8a96

추가 파라미터

Parameter	Required	Description	비고
path	Y	UnZIP할 FTP에서의 파일 경로	ex) testsubpath1/23/06/05.zip

응답 파라미터

Parameter	Description	비고
Result_code	Result code	ex) 200, 400, 401, 500
Result_msg	Result message	ex) unzip success, zip file path is not set, invalid_auth_info, error in unzip content
Path	UnZIP 대상이 된 path	ex) testsubpath1/23/06/05.zip

Request Example

JSON Body

{ "userid": "test", "passwd": "1234", "path": "testsubpath1/23/06/05.zip" } // auth_token 사용 시 { "userid": "test", "auth_token": "abc6e615-6f36-419a-b961-3a0df78f8a96", "path": "testsubpath1/23/06/05.zip" }

Response

{ "result_code": "200", "result_msg": "unzip success", "path": "testsubpath1/23/06/05.zip" }

POST

Copy / Move

Copy — 파일/디렉토리 복사

http://fileupload.cdn.cloudn.co.kr/copy

※ Content-Type: Application/json 헤더 필수. 한 번에 하나의 file 혹은 directory만 복사합니다.

Move — 파일/디렉토리 이동

http://fileupload.cdn.cloudn.co.kr/move

※ Content-Type: Application/json 헤더 필수. 한 번에 하나의 file 혹은 directory만 이동합니다.

공통 인증 파라미터

Parameter	Required	Description	비고
userid	Y	FTP user id	ex) test
passwd	택1	FTP user id password	passwd 또는 auth_token 중 1개 필수 ex) 1234
auth_token	택1	FTP user id auth token (passwd 대신 사용)	passwd 또는 auth_token 중 1개 필수 ex) 1234	ex) abc6e615-6f36-419a-b961-3a0df78f8a96

추가 파라미터 (Copy / Move 공통)

Parameter	Required	Description	비고
src	Y	복사/이동할 원본 file 혹은 directory list	ex) ["testsubpath1/23/06/05.txt", "testsubpath1/23/06"]
dest	Y	복사/이동할 목적지 경로	ex) destdir/path/directory

응답 파라미터 (Copy / Move 공통)

Parameter	Description	비고
Result_code	Result code	ex) 200, 400, 401, 500
Result_msg	Result message	Copy: copy success, error in copying content, invalid_auth_info, source or destination is not set Move: move success, error in moving content, invalid_auth_info, source or destination is not set
src	원본 file 혹은 directory
dest	목적지 경로

Copy Request Example

JSON Body

{ "userid": "test", "passwd": "1234", "src": [ "testsubpath1/23/06/05.txt", "testsubpath1/23/06" ], "dest": "destdir/path/directory" }

Copy Response

{ "result_code": "200", "result_msg": "copy success", "src": [ "testsubpath1/23/06/05.txt", "testsubpath1/23/06" ], "dest": "destdir/path/directory" }

Move Request

{ "userid": "test", "passwd": "1234", "src": [ "testsubpath1/23/06/05.txt", "testsubpath1/23/06" ], "dest": "destdir/path/directory" }

Move Response

{ "result_code": "200", "result_msg": "move success", "src": ["testsubpath1/23/06/05.txt"], "dest": "destdir/path/directory" }

POST

Mkdir / Rename

Mkdir — 디렉토리 생성

http://fileupload.cdn.cloudn.co.kr/mkdir

※ Content-Type: Application/json 헤더 필수. 한 번에 하나의 directory만 생성. 중간 directory가 없으면 모두 생성합니다.

Rename — 파일/디렉토리 이름 변경

http://fileupload.cdn.cloudn.co.kr/rename

※ Content-Type: Application/json 헤더 필수. 한 번에 하나의 file 혹은 directory만 rename합니다.

공통 인증 파라미터

Parameter	Required	Description	비고
userid	Y	FTP user id	ex) test
passwd	택1	FTP user id password	passwd 또는 auth_token 중 1개 필수 ex) 1234
auth_token	택1	FTP user id auth token (passwd 대신 사용)	passwd 또는 auth_token 중 1개 필수 ex) 1234	ex) abc6e615-6f36-419a-b961-3a0df78f8a96

Mkdir 추가 파라미터

Parameter	Required	Description	비고
path	Y	생성해야 할 directory 경로	ex) testsubpath1/23/06

Mkdir 응답

Parameter	Description	비고
Result_code	Result code	ex) 200, 400, 401, 500
Result_msg	Result message	ex) success, invalid_auth_info
path	생성된 directory 경로	ex) testsubpath1/23/06

Rename 추가 파라미터

Parameter	Required	Description	비고
src	Y	rename할 원본 file 혹은 directory	ex) "testsubpath1/23/06/05.txt"
dest	Y	rename할 목적지 경로	ex) destdir/path/directory/dest

Rename 응답

Parameter	Description	비고
Result_code	Result code	ex) 200, 400, 401, 500
Result_msg	Result message	ex) move success, error in moving content, invalid_auth_info, source or destination is not set
src	rename 원본 file 혹은 directory
dest	rename 목적지 경로

Mkdir Example

JSON Body

{ "userid": "test", "passwd": "1234", "path": "testsubpath1/23/06" }

Mkdir Response

{ "result_code": "200", "result_msg": "mkdir success", "path": "testsubpath1/23/06" }

Rename Request

{ "userid": "test", "passwd": "1234", "src": "testsubpath1/23/06/05.txt", "dest": "destdir/path/directory/dest" }

Rename Response

{ "result_code": "200", "result_msg": "move success", "src": "testsubpath1/23/06/05.txt", "dest": "destdir/path/directory/dest" }

GET

Download

http://fileupload.cdn.cloudn.co.kr/download?userid=&passwd=&path=

※ GET 방식 사용. Content-Type 헤더 불필요. 모든 항목은 URL encoding 값으로 설정.

CDN Storage 상의 content를 HTTP protocol로 다운받는 기능입니다. Query parameter로 userid, passwd, path를 설정합니다.

요청 파라미터 (URL Query String)

Parameter	Required	Description	비고
userid	Y	FTP user id	ex) test
passwd	택1	FTP user id password	passwd 또는 auth_token 중 1개 필수
auth_token	택1	FTP user id auth token	passwd 또는 auth_token 중 1개 필수
path	Y	다운 받을 content file 경로	URL encoding 필수 ex) testsubpath1%2F16%2F06%2F05.txt

응답 (오류 시)

Parameter	Description	비고
Result_code	Result code	ex) 400, 401, 403, 404, 500
Result_msg	Result message	ex) does not exists, Directory could not be downloaded, invalid_auth_info, internal server error
path	다운 받을 content file 경로

Request URL Example

passwd 사용

http://fileupload.cdn.cloudn.co.kr/download ?userid=test &passwd=1234 &path=testsubpath1%2F16%2F06%2F05.txt

auth_token 사용

http://fileupload.cdn.cloudn.co.kr/download ?userid=test &auth_token=abc6e615-6f36-419a-b961-3a0df78f8a96 &path=testsubpath1%2F16%2F06%2F05.txt

Error Response (404)

{ "result_code": "404", "result_msg": "does not exists", "path": "testsubpath1/23/06/05.txt" }

PUT

Upload (PUT)

http://fileupload.cdn.cloudn.co.kr/uploadput?userid=&passwd=&subpath=&filename=

※ PUT 방식. Content-Type: application/octet-stream 및 Content-Length 헤더 필수. 모든 query 항목은 URL encoding.

Client에서 local file을 서버로 HTTP PUT method를 이용하여 upload합니다.

요청 파라미터 (URL Query String)

Parameter	Required	Description	비고
userid	Y	FTP user id	ex) test
passwd	택1	FTP user id password	passwd 또는 auth_token 중 1개 필수
auth_token	택1	FTP user id auth token	passwd 또는 auth_token 중 1개 필수
subpath	Y	Upload할 컨텐츠가 저장될 directory 경로	URL encoding 필수 ex) testsubpath1%2F16%2F06
filename	Y	Upload할 컨텐츠가 저장될 file name	ex) 05.txt

응답 파라미터

Parameter	Description	비고
Result_code	Result code	ex) 200, 400, 401, 403, 500
Result_msg	Result message	ex) success, file name isn't defined, Directory(its name is same with file name) exists on remote file path, invalid_auth_info, error in writing file, error in renaming file, internal server error
subpath	컨텐츠가 저장된 directory 경로	ex) testsubpath1/23/06
filename	저장된 file name	ex) 05.txt

Request URL Example

passwd 사용

http://fileupload.cdn.cloudn.co.kr/uploadput ?userid=test &passwd=1234 &subpath=testsubpath1%2F16%2F06 &filename=05.txt

auth_token 사용

http://fileupload.cdn.cloudn.co.kr/uploadput ?userid=test &auth_token=abc6e615-6f36-419a-b961-3a0df78f8a96 &subpath=testsubpath1%2F16%2F06 &filename=05.txt

Response

{ "result_code": "200", "result_msg": "success", "subpath": "testsubpath1/23/06", "filename": "05.txt" }

에러 코드

Upload API 서버의 응답(오류) 코드입니다.

2XX — 성공

코드	내역	비고
200	요청 성공	요청에 대한 처리 완료

4XX — 클라이언트 오류

코드	내역	비고
400	Bad Request	필수 파라미터 누락 또는 형식 오류 (ex: path is not set)
401	Unauthorized	ID/Password 불일치 또는 인증 정보 누락
403	Forbidden	권한 없음 (ex: 디렉토리 다운로드 시도 등)
404	Not Found	CDN Storage 상에 해당 경로가 존재하지 않음

5XX — 서버 오류

코드	내역	비고
500	Internal Error	내부 오류 (ex: error in writing file, error in unzip content)

에러 응답 예시 (JSON)

// 401 — 인증 오류 { "result_code": "401", "result_msg": "invalid_auth_info" }

// 404 — 경로 없음 { "result_code": "404", "result_msg": "does not exists", "path": "testsubpath1/23/06/05.txt" }

// 400 — 파라미터 오류 { "result_code": "400", "result_msg": "path is not set" }

💡 에러 발생 시 result_code와 result_msg로 원인을 확인하십시오.