Object_File & Folder
You can use the Object:File&Folder API to create files/folders and manage related information and policies.
API preparations
Please refer to the API Preparation for the preparatory work required to call the API.
API endpoint
The Object Storage API endpoint for API requests is:
Object_File & Folder API endpoint format
https://objectstorage.kr-central-2.kakaocloud.com
Supported specifications
Object REST-API supports Openstack's Swift API specification.
| Object REST-API | Swift API specification |
|---|---|
| Account | Bucket account |
| Container | Bucket name |
| Object | Folder and file - Folder example: images/small<br/> - File example: image/small/icon.jpg |
Create folder
Users with Owner, Read-Write permissions can create folders in the bucket.
Request Syntax
Request Syntax
curl --location --request PUT 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/directory' \
--header 'X-Object-Meta-Company: kakao enterprise'
API method
| method | Request URL |
|---|---|
| PUT | https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path} |
| Path | Type | Required or not | Description |
|---|---|---|---|
| region_name | String | Required | Region name |
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| path | String | Required | Full folder path - Example: image/small, images/small/icon.jpg |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
| Content-Type | String | Required | Pinned to application/directory |
X-Object-Meta-{key_name} | String | Select | As bucket meta information, enter the metadata name to be specified by the user in {key_name} - For Swift API, apply the corresponding prefix |
X-Object-Meta-{key_name} | String | Select | As bucket meta information, enter the metadata name to be specified by the user in {key_name} - For S3 API, apply the corresponding prefix |
Response Syntax
Status Code
| HTTP Status | Response | Description |
|---|---|---|
201 | Created | Success |
401 | Unauthorized | Authentication failed |
403 | Forbidden | No permission |
Create and upload files
Users with Owner, Read-Write permissions can create or upload files in the bucket.
Request Syntax
Request Syntax
curl --location --request PUT 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}/{file}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: text/plain' \
--data-raw '{Content}'
API method
| method | Request URL |
|---|---|
| PUT | https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}/{file} |
| Path | Type | Required or not | Description |
|---|---|---|---|
| region_name | String | Required | Region name |
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| path | String | Required | Full folder path - Example: image/small, images/small/icon.jpg |
| file | String | Required | File name - Example: icon.jpg |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
| Content-Type | String | Select | If the object being put (uploaded) is a file, enter the mime type string - If no content type is specified during a Put (upload) request, Object Storage internally processes the uploaded file type as application/octet-stream. |
X-Object-Meta-{name} | String | Select | For bucket meta information, enter the metadata name to specify in {name} |
| Content-Length | int | Select | Content Length |
| Transfer-Encoding | String | Select | Encoding method - chunked: Data is transmitted by dividing it into a series of chunks. If the chunked value is specified, the Content-Length Header should not be transmitted- compress: LZW Compression method using the algorithm- deflate: Compression method using the deflate algorithm- gzip : Compression method using the LZ77 algorithm- identity: Compression or modification transmission method without |
Request body Elements
| Request | Type | Required or not | Description |
|---|---|---|---|
| Content | Raw data | Required | Contents of file |
Response Syntax
Status Code
| HTTP Status | Response | Description |
|---|---|---|
201 | Created | Success |
401 | Unauthorized | Authentication failed |
403 | Forbidden | No permission |
Upload large-size file
Since the HTTP protocol does not have a keep-alive feature, data transfer ends when the TCP connection is lost. Therefore, when uploading a large file through a single connection, the upload may be interrupted if the connection is unstable or the connection is lost. KakaoCloud Object Storage supports the following large object upload methods to upload large files.
caution
- Not available on encrypted buckets in kr-central-2.
- When uploading a file with the same name but a different capacity by overwriting it, segment files may remain.
- We recommend deleting remaining segment files through object inquiry.
Upload large object
| method | Description |
|---|---|
| Dynamic Large Object (DLO) | Ensures that the divided Segment Object is recognized as a single Large Object - Swift protocol |
| Static Large Object (SLO) | Segments are split and uploaded, but there are no restrictions on segment naming and the sizes do not have to be the same - Swift protocol |
DLO (Dynamic Large Object) method
The DLO method allows divided segment objects to be recognized as a single large object. Additionally, the integrity of each segment object is not guaranteed. When downloading (GET), the user requests to download the Manifest object. And the Object Storage server recognizes the X-Object-Manifest entered in Manifest Object and allows segment object to be recognized as a single large object.
- Segment one single large object into a certain size.
- Upload the divided object to the object manifest.
- Upload the Manifest Object containing the items in the X-Object-Manifest header. At this time, you can upload the manifest object first.
Upload DLO Segment Object
Request Syntax
Request Syntax
curl --location --request PUT 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object}/{Segment Objects...}' \
--header 'X-Auth-Token: {x-auth-token}' \
--data-raw '{segment_content}'
Upload DLO segment object
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/test-bucket/DLO/00000001 --data-binary '1'
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/test-bucket/DLO/00000002 --data-binary '2'
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/test-bucket/DLO/00000003 --data-binary '3'
API method
| method | URL |
|---|---|
| PUT | https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object}/{Segment Objects… } |
| Path | Type | Required or not | Description |
|---|---|---|---|
| region_name | String | Required | Region name |
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| DLO Manifest Object | String | Required | Name of manifest object |
| Segment Objects… | String | Required | Multiple Segment Objects can be uploaded - Sequence Number Naming in ascending order is required (example: segment_0001 ... segment_0002) |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
Request Elements
| Request | Type | Required or not | Description |
|---|---|---|---|
| segment_content | Data-raw | Required | Contents of segment object |
Response Syntax
Status Code
| HTTP Status | Response | Description |
|---|---|---|
201 | Created | Success |
Upload DLO Manifest Object
Request Syntax
Request Syntax
curl --location --request PUT 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'X-Object-Manifest: {bucket_name}/{DLO Manifest Object}' \
Example of uploading DLO manifest object
curl -X PUT -H 'X-Auth-Token: <token>' -H 'X-Object-Manifest: test-bucket/DLO' https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/test-bucket/DLO --data-binary ''
API method
| method | URL |
|---|---|
| PUT (Upload segmented object) | https:/objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object}/{Segment Object… } |
| PUT (uploads the Manifest Object itself) | https:/objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object} |
| Path | Type | Required or not | Description |
|---|---|---|---|
| region_name | String | Required | Region name |
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| DLO Manifest Object | String | Required | Name of manifest object |
| Segment Object… | String | Required | Multiple Segment Objects can be uploaded |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
| X-Object-Manifest | String | Required | Path where the divided Segment Objects were uploaded - {bucket_name}/{DLO Manifest Object} format |
Response Syntax
Status Code
| HTTP Status | Response | Description |
|---|---|---|
201 | Created | 성공 |
Download DLO
Request Syntax
Request Syntax
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object}' \
--header 'X-Auth-Token: {x-auth-token}' \
DLO download example
curl -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/test-bucket/DLO
API method
| method | URL |
|---|---|
| PUT | https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{DLO Manifest Object} |
| Path | Type | Required or not | Description |
|---|---|---|---|
| region_name | String | Required | Region name |
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| DLO Manifest Object | String | Required | Name of manifest object |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
Response Syntax
Status Code
| HTTP Status | Response | Description |
|---|---|---|
201 | Created | Success |
SLO (Static Large Object) method
The SLO method divides and uploads segments in the same way as DLO, but the difference is that there are no restrictions on segment naming and the sizes do not have to be the same. Also, the Manifest must be uploaded last. The SLO Manifest Object must be entered by creating a list of Segment Objects in order. Currently, in KakaoCloud object storage, up to 1,000 Segment Objects can be entered into one Manifest.
When requesting SLO Manifest Object creation, it is checked whether each Segment Object is in the entered path and whether the etag Value and Segment Object Size match. If the information does not match, the Manifest Object is not created. Additionally, the integrity of the Segment Object is guaranteed through etag in the Manifest.
- Segment one single large object into the size desired by the user.
- Upload each Segment to a bucket you have access to. It does not have to be the same bucket, but it must be a project (account) bucket that you have access to.
- Enter the Manifest containing the Path, Etag, and Size of the uploaded Segment object above as the Body and upload the SLO Manifest Object.
info
For detailed examples of Manifest, please refer to https://objectstorage.kr-central-1.kakaocloud.com/info.
Upload SLO Segment Object
Request Syntax
Request Syntax
curl --location --request PUT 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}/{segment_object}' \
--header 'X-Auth-Token: {x-auth-token}' \
--data-raw '{segment_content}'
Example of uploading SLO segment object
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/test-bucket/slo_test_1.txt --data-binary '@./slo_test_1.txt'
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/other-bucket/slo_test_2.txt --data-binary '@./slo_test_2.txt'
curl -X PUT -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/other1-bucket/slo_test_3.txt --data-binary '@./slo_test_3.txt'
API method
| method | URL |
|---|---|
| PUT | https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}/{segment_object} |
| Path | Type | Required or not | Description |
|---|---|---|---|
| region_name | String | Required | Region name |
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| path | String | Required | Path where segment object was uploaded |
| segment_object | String | Required | Segment object name |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
Request Elements
| Request | Type | Required or not | Description |
|---|---|---|---|
| segment_content | Raw-data | Required | Contents of segment object |
Response Syntax
Status Code
| HTTP Status | Response | Description |
|---|---|---|
201 | Created | Success |
Upload SLO Manifest
Request Syntax
Request Syntax
curl --location --request PUT 'https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/{bucket_name}/{SLO Manifest Object}?multipart-manifest=put' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: "application/json"' \
--data '[ \
{
"path": "{path}/{Segment Object}",
"etag": "{Segment Object의 etag 값}",
"size_bytes": "{Segment Object Size}"
},
....
]
}'
SLO Manifest Object upload example
curl -X PUT -H 'X-Auth-Token: <token>' -H 'Content-Type: application/json' https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/bucket/SLO?multipart-manifest=put
--data
'
[
{
"path": "test-bucket/slo_test_1.txt",
"etag": "ba1f2511fc30423bdbb183fe33f3dd0f",
"size_bytes": 4
},
{
"path": "other-bucket/slo_test_2.txt",
"etag": "441295deac01cf5d6bdc7db3173adfdf",
"size_bytes": 1369
},
{
"path": "other1-bucket/slo_test_3.txt",
"etag": "aa3f5bb8c988fa9b75a1cdb1dc4d93fc",
"size_bytes": 4
}
]
'
API method
| method | URL |
|---|---|
| PUT | https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/{bucket_name}/{SLO Manifest Object}?multipart-manifest=put |
| Path | Type | Required or not | Description |
|---|---|---|---|
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| SLO Manifest Object | String | Required | Name of manifest object |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
| Content-Type | String | Required | Type of content |
Request Elements
| Request | Type | Required or not | Description |
|---|---|---|---|
| path | String | Required | Enter in the format {path}/{Segment Object} - {path}: Path to upload the object - {Segment Object}: Segment object under path |
| etag | String | Select | Etag value of segment object |
| size_bytes | Int | Select | Segment object size |
info
After entering etag and size_bytes during Manifest PUT, compare the etag and size_bytes values of the existing uploaded segment object and generate an error if they do not match.
Response Syntax
Status Code
| HTTP Status | Response | Description |
|---|---|---|
201 | Created | Success |
Download SLO
Request Syntax
Request Syntax
curl --location --request GET 'https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/{bucket_name}/{SLO Manifest Object}' \
--header 'X-Auth-Token: {x-auth-token}' \
SLO download example
curl -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/bucket/SLO
API method
| method | URL |
|---|---|
| PUT | https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/{bucket_name}/{SLO Manifest Object} |
| Path | Type | Required or not | Description |
|---|---|---|---|
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| SLO Manifest Object | String | Required | Name of manifest object |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
Response Syntax
Status Code
| HTTP Status | Response | Description |
|---|---|---|
201 | Created | Success |
Download SLO Manifest
For SLO, only the SLO Manifest Object can be downloaded separately. If you request multipart-manifest=get as a query param, you can download only the manifest.
Request Syntax
Request Syntax
curl --location --request GET 'https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/{bucket_name}/{SLO Manifest Object}?multipart-manifest=get' \
--header 'X-Auth-Token: {x-auth-token}' \
SLO Manifest Object Download Example
curl -H 'X-Auth-Token: <token>' https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/test-bucket/SLO?multipart-manifest=get
API method
| method | URL |
|---|---|
| PUT | https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/{bucket_name}/{SLO Manifest Object}?multipart-manifest=get |
| Path | Type | Required or not | Description |
|---|---|---|---|
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| SLO Manifest Object | String | Required | Name of manifest object |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
Response Syntax
Status Code
| HTTP Status | Response | Description |
|---|---|---|
201 | Created | Success |
Upload multipart
- Provides Multipart-upload API extension of OpenStack Swift Object API. This allows you to upload large files in a similar way to the S3 Multipart-upload API.
- S3 Multipart-upload API is a function provided by AWS that uploads large files by splitting the file into several pieces, uploading them, and then recombining them. For more information about the S3 Multipart-upload API, please refer to S3 Multipart Upload API Documentation.
- Object Storage does not support Swift SLO (static large object) and DLO (dynamic large object) APIs.
A multipart upload consists of three steps:
Step 1. Create multi-part upload
Request Syntax
Request Syntax
curl --location --request POST 'https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/{path}?uploads' \
--header 'X-Auth-Token: {x-auth-token}'
API method
| method | Request URL |
|---|---|
| POST | https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/{path}?uploads |
| Path | Type | Required or not | Description |
|---|---|---|---|
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| path | String | Required | Full folder path - Example: image/small, images/small/icon.jpg |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
Response Syntax
Multipart Upload Creation Response Syntax
<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult>
<Tenant>{tenant-id}</Tenant>
<Bucket>{bucket-name}</Bucket>
<Key>{object-path}</Key>
<UploadId>{upload-id}</UploadId>
</InitiateMultipartUploadResult>
Response Elements
| Response | Type | Description |
|---|---|---|
| tenant-id | String | Project ID |
| bucket-name | String | Bucket name |
| object-path | String | File path |
| upload-id | String | Unique ID of the large object assigned by the server |
Status Code
| HTTP Status | Response | Description |
|---|---|---|
201 | Created | Success |
401 | Unauthorized | Authentication failed |
403 | Forbidden | No permission |
Step 2. Upload partial parts
Parts must be 5MB or larger to be uploaded.
Request Syntax
Request Syntax
curl --location --request PUT 'https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/{path}?uploadId={upload-id}&partNumber={part -number}'\
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/octet-stream' \
--data '{path_name}'
API method
| method | Request URL |
|---|---|
| PUT | https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/{path}?uploadId={upload-id}&partNumber={part-number} |
| Path | Type | Required or not | Description |
|---|---|---|---|
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| path | String | Required | Full folder path - Example: image/small, images/small/icon.jpg |
Request Query
| Request | Type | Required or not | Description |
|---|---|---|---|
| uploadId | Query | Required | Unique upload id of the large object returned by CreateMultipartUpload |
| partNumber | Query | Required | Number of parts in the large object of the currently uploaded file (1~10000) |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
Response Header
| Response | Type | Description |
|---|---|---|
| etag | String | etag of the currently uploaded partial file |
Status Code
| HTTP Status | Response | Description |
|---|---|---|
200 | Created | Success |
401 | Unauthorized | Authentication failed |
403 | Forbidden | No permission |
Step 3. Multipart upload completed
Request Syntax
Request Syntax
curl --location --request PUT 'https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/{path}?uploadId={upload-id}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/xml' \
--data '<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUpload>
<Part>
<ETag>"<etag of 5MB_1.file>"</ETag>
<PartNumber>1</PartNumber>
</Part>
<Part>
<ETag>"<etag of 5MB_2.file>"</ETag>
<PartNumber>2</PartNumber>
</Part>
<Part>
<ETag>"<etag of remain.file>"</ETag>
<PartNumber>3</PartNumber>
</Part>
</CompleteMultipartUpload>'
API method
| method | Request URL |
|---|---|
| PUT | https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/{path}?uploadId={upload-id} |
| Path | Type | Required or not | Description |
|---|---|---|---|
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| path | String | Required | Full folder path - Example: image/small, images/small/icon.jpg |
Request Query
| Request | Type | Required or not | Description |
|---|---|---|---|
| uploadId | Query | Required | Unique upload id of the large object returned by CreateMultipartUpload |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
Response Elements
| Response | Type | Description |
|---|---|---|
| ETag | String | ETag of the currently uploaded partial file |
| PartNumber | Integer | Number of currently uploaded partial file |
Status Code
| HTTP Status | Response | Description |
|---|---|---|
201 | Created | Success |
401 | Unauthorized | Authentication failed |
403 | Forbidden | No permission |
Manage object
Query object meta
Users with Owner, Read-Only, Read-Write permissions can query information about the bucket. They can also access metadata for objects (files, folders) stored in the bucket.
Request Syntax
Request Syntax
curl --location --request HEAD 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}' \
--header 'X-Auth-Token: {x-auth-token}'
API method
| method | Request URL |
|---|---|
| HEAD | https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path} |
| Path | Type | Required or not | Description |
|---|---|---|---|
| region_name | String | Required | Region name: kr-central-2 |
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| path | String | Required | Full folder path - Example: image/small, images/small/icon.jpg |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
Response Syntax
Status Code
| HTTP Status | Response | Description |
|---|---|---|
200 | Success | Success |
401 | Unauthorized | Authentication failed |
403 | Forbidden | No permission |
Change object meta
Users with Owner, Read-Write permissions can make changes to the bucket.
The following is how to change the metadata of objects (files, folders) stored in the bucket.
Request Syntax
Request Syntax
curl --location --request POST 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'X-Object-Meta-Company: kakao enterprise'
API method
| method | Request URL |
|---|---|
| POST | https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path} |
| Path | Type | Required or not | Description |
|---|---|---|---|
| region_name | String | Required | Region name |
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| path | String | Required | Full folder path - Example: image/small, images/small/icon.jpg |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
X-Object-Meta-{name} | String | Select | For bucket meta information, enter the metadata name to specify in {name} |
Response Syntax
Status Code
| HTTPS Status | Response | Description |
|---|---|---|
200 | Success | Success |
401 | Unauthorized | Authentication failed |
403 | Forbidden | No permission |
Query object list
Users with Owner, Read-Write, Read-Only permissions can query the bucket. View the list of objects (files, folders) stored in the bucket.
Request Syntax
Request Syntax
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}?format=json' \
--header 'X-Auth-Token: {x-auth-token}'
API method
| method | Request URL |
|---|---|
| GET | https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name} |
| Path | Type | Required or not | Description |
|---|---|---|---|
| region_name | String | Required | Region name |
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
Request Query
| Request | Type | Required or not | Description |
|---|---|---|---|
| prefix | Query | Select | Directory path - Example: image/small |
| delimiter | Query | Select | When using delimiter as a key, / input is required |
| limit | Query | Select | Number of lists - Default: 1000 (up to 1,000 items can be searched) |
| marker | Query | Select | Search conditions - (Object name > Marker ) |
| format | Query | Select | Format to receive response - plain (default)- json- xml |
Response Syntax
JSON ObjectList
{
name: String
content_type: String
bytes: int
hash: String
last_modified: String // Last modified date RFC3339 example: 2020-07-01T00:00:00Z
subdir: String // In case of pseudo-directory, only this value is provided
}
Object List Search Response Syntax
[
{
"name": "document",
"content_type": "application/directory",
"bytes": 0,
"hash": "d41d8cd98f00b204e9800998ecf8427e",
"last_modified": "2020-06-26T11:12:03+09:00"
},
{
"name": "document/hello.txt",
"content_type": "application/octet-stream",
"bytes": 7,
"hash": "083d9fe8506415ba02f2f86e0531527f",
"last_modified": "2020-06-26T11:14:50+09:00"
}
]
Response Elements
| Response | Type | Description |
|---|---|---|
| name | String | Object name |
| content_type | String | The content-type value provided during the PUT request for the object is returned. - Type: directory / image / classification binary, etc. |
| bytes | int | Object size |
| hash | String | Unique file value |
| last_modified | String | Last modified date - Format: RFC3339 - Example: 2020-07-01T00:00:00Z |
| subdir | String | This value is only provided if pseudo-directory |
Status Code
| HTTPS Status | Response | Description |
|---|---|---|
200 | OK | Success |
401 | Unauthorized | Authentication failed |
403 | Forbidden | No permission |
Download object
Users with Owner, Read-Write, Read-Only permissions can download objects in the bucket. .
If the path is Folder, content with size 0 is received in response. To search the sublist of a folder, you must use the Query object list API.
Request Syntax
Request Syntax
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}' \
--header 'X-Auth-Token: {x-auth-token}'
API method
| method | Request URL |
|---|---|
| GET | https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/:path |
| Path | Type | Required or not | Description |
|---|---|---|---|
| region_name | String | Required | Region name |
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| path | String | Required | Full folder path - Example: image/small, images/small/icon.jpg |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
Response Syntax
Response Syntax
{
Content-Length (Header)
Content-Type (Header)
Last-Modified (Header)
ETag (Header)
Content (Body)
}
Response Header
| Response | Type | Description |
|---|---|---|
| Content-Length | int | Size value of the object - If it is a file, the file size value is passed. - If it is a folder, only meta information is sent and a value of 0 is passed. |
| Content-Type | String | Type of content |
| Last-Modified | String | Last modified date |
| ETag | String | ETag is an MD5 hash value for the binary, so in the case of a folder where the binary does not exist, a meaningless value is transmitted |
Response Elements
| Response | Type | Description |
|---|---|---|
| Content | Raw data | Not delivered if content type is folder |
Status Code
| response code | Response | Description |
|---|---|---|
200 | OK | Success |
401 | Unauthorized | No permission |
404 | Not found | File not found |
Delete object
Users with Owner, Read-Write permissions can delete objects in a bucket.
Request Syntax
Request Syntax
curl --location --request DELETE 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}' \
--header 'X-Auth-Token: {x-auth-token}'
API method
| method | Request URL |
|---|---|
| DELETE | https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path} |
| Path | Type | Required or not | Description |
|---|---|---|---|
| region_name | String | Required | Region name |
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| path | String | Required | Full folder path - Example: image/small, images/small/icon.jpg |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
Response Syntax
Status Code
| HTTPS Status | Response | Description |
|---|---|---|
204 | No Content | Success |
401 | Unauthorized | No permission |
404 | Not found | File not found |
Copy object
You must have read permission on the object to be copied and write permission (Read-Write permission) on the object to be copied.
Request Syntax
Request Syntax
curl --location --request COPY 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Destination: /{target-bucket-name}/{target-path}'
API method
| method | Request URL |
|---|---|
| COPY | https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path} |
| Path | Type | Required or not | Description |
|---|---|---|---|
| region_name | String | Required | Region name |
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| path | String | Required | Full folder path - Example: image/small, images/small/icon.jpg |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
| Destination | String | Required | Path name of destination to copy - Example: {target-bucket-name}/{target-path} |
Response Syntax
Status Code
| HTTPS Status | Response | Description |
|---|---|---|
201 | Created | Success |
401 | Unauthorized | No permission |
404 | Not found | File not found |
Move object
To move an object, you need the storage.objects.get permission on the bucket containing the object to be moved, and the storage.objects.create permission on the bucket where the object will be moved.
info
Moving an object is not available on encrypted buckets in kr-central-2.
Request Syntax
Request Syntax
curl --location --request MOVE 'https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/{bucket_name}/{path}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Destination: /{target-bucket-name}/{target-path}'
API method
| method | Request URL |
|---|---|
| MOVE | https://objectstorage.kr-central-1.kakaocloud.com/v1/{account}/{bucket_name}/{path} |
| Path | Type | Required or not | Description |
|---|---|---|---|
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| path | String | Required | Full folder path - Example: image/small, images/small/icon.jpg |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
| Destination | String | Required | Path of destination to move to - Example: {target-bucket-name}/{target-path} |
Response Syntax
Status Code
| HTTPS Status | Response | Description |
|---|---|---|
201 | Created | Success |
401 | Unauthorized | No permission |
404 | Not found | File not found |
Create temp URL for downloading object
Users with access to the object create a Temp URL for download that is valid for a specific period of time. temp_url_expires is the effective time and sets it to allow downloading until the time specified by the user.
Request Syntax
Request Syntax
curl --location --request GET 'https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/{path}?temp_url&temp_url_expires={temp_url_expires}' \
--header 'X-Auth-Token: {x-auth-token}'
API method
| Method | Request URL |
|---|---|
| GET | https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/{path}?temp_url&temp_url_expires={temp_url_expires} |
| Path | Type | Required or not | Description |
|---|---|---|---|
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as account value in Swift API |
| bucket_name | String | Required | Bucket name |
| path | String | Required | Full path to folder - Example: image/small, images/small/icon.jpg |
Request Header
| Request | Type | Required or not | Description |
|---|---|---|---|
| X-Auth-Token | String | Required | Authentication token |
Request Query
| Request | Type | Required or not | Description |
|---|---|---|---|
| temp_url | String | Required | The key indicating a request for issuing a TempUrl |
| temp_url_expires | Timestamp | Required | Validity time of issued TempUrl - Unit: sec |
Response Syntax
Response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Thu, 09 Mar 2023 04:44:00 GMT
Content-Length: 209
{
"url": "/v1/{project_id}/object-reg-test-1/test.txt?temp_url_sig={temp_url_sig}&temp_url_expires={temp_url_expires}",
"sig": "{sig}"
}
Response Elements
| Response | Type | Description |
|---|---|---|
| url | String | Temporary URL where you can download the object within the expire time |
| sig | String | This is the signature of the URL and is valid within the object's expire time |
Status Code
| HTTPS Status | Response | Description |
|---|---|---|
200 | Unauthorized | Authentication failed |
403 | Forbidden | No permission |
404 | Not found | No bucket |
Download object using temp URL
The generated Temp URL allows you to download the object during the validity period requested at the time of issuance. When using a Temp URL, it can be downloaded without an X-Auth-Token, so the issuer of the Temp URL must pass it on to a trusted user.
Request Syntax
Request Syntax
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}?temp_url_sig={temp_url_sig}&temp_url_expires={temp_url_expires}'
API method
| method | Request URL |
|---|---|
| GET | https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{path}?temp_url_sig=value&temp_url_expires={temp_url_sig}&filename={temp_url_expires} |
| Path | Type | Required or not | Description |
|---|---|---|---|
| region_name | String | Required | Region name |
| account | String | Required | Project ID - Able to get this information when issuing a token - Used as the account value in Swift API |
| bucket_name | String | Required | Bucket name |
| path | String | Required | Full folder path - Example: image/small, images/small/icon.jpg |
Request Query
| Request | Type | Required or not | Description |
|---|---|---|---|
| temp_url_sig | Query | Required | Signature information of issued temp URL response |
| temp_url_expires | Query | Required | Valid time information of issued Temp URL response - Unit: Unix epoch time |
| filename | Query | Select | Custom file name to use when downloading the object from the browser - utf-8 percent encoded string |
Response Syntax
Response
{
Content-Length (Header)
Content-Type (Header)
Last-Modified (Header)
ETag (Header)
Content-Disposition (Header)
Content (Body)
}
Response Header
| Response | Type | Description |
|---|---|---|
| Content-Length | int | Size value of the object - If it is a file, the file size value is transmitted. - In the case of a folder, only meta information is sent, so a value of 0 is transmitted. |
| Content-Type | String | Media type |
| Last-Modified | String | Last modified date |
| ETag | String | ETag is an MD5 hash value for the binary, so in the case of a folder where the binary does not exist, a meaningless value is transmitted |
| Content-Disposition | String | The filename for the browser to save the file locally when downloading an object. - Default value: Object name - A utf-8 percent encoded string is sent |
Response Elements
| Response | Type | Description |
|---|---|---|
| Content | Body | Not delivered if content type is folder |
Status Code
| HTTPS Status | Response | Description |
|---|---|---|
200 | Success | Success |
403 | Forbidden | Temp URL expiration time |