Spaces provides a RESTful XML API for programmatically managing the data you store through standard HTTP requests. The API is interoperable with Amazon’s AWS S3 API, allowing you to interact with the service with any S3-compatible tools.
Spaces and Spaces CDN supports HTTP/2 and HTTP/1.1 clients. Any HTTP/2 conformant client receives HTTP/2 responses, otherwise HTTP/1.1 responses are returned. Some HTTP/2 requests are downgraded to HTTP/1.1 for operational reasons, as permitted by the HTTP/2 specification.
You can use the Spaces API in the following ways:
To use AWS S3, check for AWS S3 Compatibility, test your environment with a “Hello, World!” Program, and see additional examples in Using DigitalOcean Spaces with AWS S3 SDKs.
To make calls to the Spaces API, create your authentication header, optionally configure your call with Access Control Lists (ACLs) and other common headers, and call one of the operations under Bucket Operations or Object Operations.
For the full list of supported S3 API commands, see Supported S3 Commands.
The Spaces API aims to be interoperable with Amazon’s AWS S3 API. In most cases, when using a client library, setting the endpoint or base URL to ${REGION}.digitaloceanspaces.com
and generating a Spaces key pair to replace your AWS IAM key pair allows you to use Spaces in place of S3.
Spaces provides support for create, read, update, and delete (CRUD) operations for both buckets (Spaces) and objects as well as the ability to define access control lists (ACLs). Some S3 features are not supported as show in the table below:
Feature | Supported | Notes |
---|---|---|
Bucket CRUD | Yes | |
Object CRUD | Yes | |
Object Copy | Yes | Cross region copying is not supported. For regions with multiple clusters, cross-cluster copying is not supported. |
Multipart Uploads | Yes | |
Presigned URLs | Yes | Both v2 and v4 signature types are supported. |
Bucket ACLs | Yes | |
Object ACLs | Yes | |
Identity and Access Management (IAM) | No | |
Security Token Service (STS) | No | |
Multi-factor Authentication | No | |
Public Access Block | No | |
Bucket Policies | Yes | API only |
Object Policies | No | |
Bucket Versioning | Yes | API only; not accessible through the control panel. |
Bucket Replication | No | |
Bucket Notifications | No | |
Bucket Tagging | No | |
Object Tagging | Yes | |
Request Payment | No | |
Bucket Lifecycle | Yes | Object expiration and removing incomplete multipart uploads are supported. Lifecycle policies based on object tagging are not supported. |
Bucket Inventory | No | |
Bucket Access Logging | No | |
Bucket Metrics | No | |
Bucket Analytics | No | |
Bucket Accelerate | No | |
Bucket Encryption Configuration | No | |
Object Encryption | Yes | Customer-provided encryption keys (SSE-C) are supported. |
Bucket Websites | Yes | See PutBucketWebsite command for details. CDN not supported. |
Object Torrent | No | |
Object Lock | No |
API requests for S3 functionality that is not supported by Spaces receive an S3-compatible, XML-formatted NotImplemented
error response.
The AWS S3 API is compatible with JavaScript, Go, PHP, Python 3, and Ruby. For example, the following code returns a list of Spaces (or buckets) in your specified region:
For additional examples, see Using DigitalOcean Spaces with AWS S3 SDKs.
After creating a new Space, you can upload a “Hello, World!” object to it:
For additional examples, see Using DigitalOcean Spaces with AWS S3 SDKs.
Requests to the Spaces API must include an HTTP Authorization
header. The AWS v4 Signature type is supported as well as the AWS v2 Signature type for compatibility with older clients. Throughout the examples below, v4 signatures are used. When making use of a client library, signatures are generated for you automatically.
You can generate the needed Access Key and Secret Key by visiting the API section of the DigitalOcean Control Panel for your account.
A v4 signature consists of several parts. The table below describes each piece of the example individually:
Signature component | Description |
---|---|
AWS4-HMAC-SHA256 | Indicates AWS Signature Version 4 (AWS4) and the signing algorithm (HMAC-SHA256). |
Credential | Contains your access key and information about the request in the format: ${ACCESS_KEY}/${YYYMMDD}/${REGION_SLUG}/s3/aws4_request |
SignedHeaders | A lower-cased list of the names of the request headers used when computing the signature. (for example, host;x-amz-acl;x-amz-content-sha256;x-amz-date) |
Signature | A signed hash consisting of a hash of the request body, your secret key, and information about the request (that is, the canonical request). A “pseudo-code” example is provided to demonstrate how this is calculated. |
The canonical request included in the signature is made up of:
For example, for the following request:
This would be the canonical request:
Spaces supports a limited set of access controls for buckets and objects. They can be configured by making a PUT request with an XML body consisting of an AccessControlPolicy
element. It should contain both Grantee
and Permission
elements. Grantee
may either contain the owner’s ID or a URI
element representing the AllUsers group. The available Permission
values are:
Name | Description |
---|---|
FULL_CONTROL |
Grants full access including read and write permissions to the object or bucket. |
READ |
Grants read access to the object or bucket. |
To make a bucket or object private, create an AccessControlPolicy
only containing a FULL_CONTROL
grant for the owner. To allow public read access, the AccessControlPolicy
should contain both a FULL_CONTROL
grant for the owner as well as READ
grand for the AllUsers group. (See the full reference documentation below for more information on the specific requests.)
For convenience, you can use canned ACLs in place of uploading an AccessControlPolicy
. They are a set of pre-defined access controls that can be specified through the use of the x-amz-acl
header when making a request. Currently Spaces supports these values:
Name | Description |
---|---|
private | Grants full access (FULL_CONTROL) to the owner. No unauthenticated, public access is permitted. |
public-read | Grants full access (FULL_CONTROL) to the owner while permitting unauthenticated, public READ access. |
There are a number of common headers that may be used in most requests.
Name | Description |
---|---|
Authorization | The authorization details for the request in either the AWS Signature Version 4 or AWS Signature Version 2 format (see Authentication for more information). |
Content-Length | The length in bytes of the request body. Required with PUT requests containing an XML body. |
Content-Type | The MIME type of the request body (for example, text/plain). |
Date | The current date and time date in Coordinated Universal Time (UTC) using RFC 2822 format. Example: Mon, 10 Jul 2017 19:05:09 +0000 |
Host | The target host for the request (for example, ${REGION}.digitaloceanspaces.com or ${BUCKET}.${REGION}.digitaloceanspaces.com). |
x-amz-content-sha256 | The SHA256 hash of the request payload. Required when using AWS Signature Version 4 for authentication. |
x-amz-date | The current date and time date in Coordinated Universal Time (UTC) using the ISO 8601 format: %Y%m%dT%H%M%SZ (for example, 20170803T172753Z). When provided, it takes precedence over the “Date” header. |
Likewise, these common headers may be received in most responses:
Name | Description |
---|---|
Content-Length | The length in bytes of the response body. |
Content-Type | The MIME type of the request body (for example, text/plain). |
Connection | An indicator of whether the connection to the server is open or closed. |
Date | The date and time date of the response in Coordinated Universal Time (UTC). |
ETag | The entity tag containing an MD5 hash of the object. |
x-amz-request-id | The unique identifier for the request. |
A bucket is a container for objects, such as image files and other data, that are stored in DigitalOcean Spaces. The following methods allow you to create, delete, and manage buckets.
To create a new bucket, send a PUT
request to ${BUCKET}.${REGION}.digitaloceanspaces.com
In addition to the common headers, the following headers may also be supplied:
Name | Description | Required |
---|---|---|
x-amz-acl | A “canned” ACL specifying access rules for the bucket (for example, private or public-read). Defaults to private |
No |
For compatibility purposes, the body of the request may contain an XML object with an element named CreateBucketConfiguration
containing configuration information for the bucket, specifically its location. As the region is also specified in the hostname, including this in the request is not strictly necessary.
Name | Description | Required |
---|---|---|
LocationConstraint | The region where the bucket will be created (for example, nyc3). | No |
To list all existing buckets in a region, send a GET
request to ${REGION}.digitaloceanspaces.com
The body of the response contains an XML element named ListAllMyBucketsResult
containing a list of XML objects with the following elements representing each bucket:
Name | Description |
---|---|
Owner | A container holding elements with information about the bucket’s owner. |
ID | An element containing the ID of the bucket’s owner as its value. |
DisplayName | An element containing the DisplayName of the bucket’s owner as its value. Provided for compatibility purposes, has the same value as the ID. |
Buckets | A container holding a list of elements describing each bucket. |
Bucket | A container holding elements with details about a single bucket. |
Name | An element containing the name of the bucket. |
CreationDate | An element containing the date of the bucket’s creation in the format: %Y-%m-%dT%H:%M:%S.%3NZ (for example, 2017-06-23T18:37:48.157Z ) |
To list the contents of a bucket, send a GET
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/
The following query parameters can be included in the request in order to filter the results included in the response:
Name | Description | Required |
---|---|---|
delimiter | A single character used to group keys. When specified, the response will only contain keys up to its first occurrence. (for example, using a slash as the delimiter can allow you to list keys as if they were folders, especially in combination with a prefix .) |
No |
marker | The key (object name) to start with when listing objects. For use with pagination (for example, when then number of objects in the result exceeds the specified max-keys ). |
No |
max-keys | The maximum number of objects to return. Valid inputs of 0 to 1,000 inclusive. | No |
prefix | A string used to group keys. When specified, the response only contains objects with keys beginning with the string. | No |
The body of the response contains an XML element named ListBucketResult
containing a list of XML objects with the following elements representing each object in the bucket:
Name | Description
Name | The name of the bucket.
Prefix | The specified prefix if supplied as a query parameter.
Marker | A key denoting where the list of objects begins. If empty, this indicates the beginning of the list.
NextMarker | Specifies the key which should be used with the maker
query parameter in subsistent requests. This is only returned if a delimiter
was provided with the request and IsTruncated
is true.
MaxKeys | The maximum number of objects to return, based on max-keys
query parameter after input validation.
IsTruncated | A boolean indicating whether all objects are included in the response.
Contents | A container holding elements with information about the objects in the bucket.
Key | The object’s key.
LastModified | The date and time that the object was last modified in the format: %Y-%m-%dT%H:%M:%S.%3NZ
(for example, 2017-06-23T18:37:48.157Z
)
ETag | The entity tag containing an MD5 hash of the object.
Size | The size of the object in bytes.
StorageClass | Provided for compatibility purposes. The value is always STANDARD.
Owner | A container holding elements with information about the bucket’s owner.
ID | An element containing the ID of the bucket’s owner as its value.
DisplayName | An element containing the DisplayName of the bucket’s owner as its value. Provided for compatibility purposes, has the same value as the ID.
To delete an empty bucket, send a DELETE
request to ${BUCKET}.${REGION}.digitaloceanspaces.com
This API call can only be used to delete an empty bucket.
Success is indicated by receiving 204 (No Content) as the response code.
If you receive 409 (BucketNotEmpty) as the response code, it means that you have objects in the bucket. You must remove all of the objects from the bucket (move or delete) before you can delete the bucket itself.
To retrieve a bucket’s location, send a GET
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?location
The body of the response contains an XML element named LocationConstraint
containing the “slug” for the region where the bucket is located.
Name | Description |
---|---|
LocationConstraint | A “slug” representing the region where the bucket is located (for example, nyc3 ). |
To retrieve a bucket’s Access Control List, send a GET
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?acl
The body of the response includes an XML element named AccessControlPolicy
containing information about the ACLs applied to the bucket.
Name | Description |
---|---|
Owner | A container holding elements with information about the bucket’s owner. |
ID | An element containing the ID of the bucket’s owner as its value. |
DisplayName | An element containing the DisplayName of the bucket’s owner as its value. Provided for compatibility purposes, has the same value as the ID. |
AccessControlList | A container holding a list of elements describing one or more access grants. |
Grant | A container for an individual access grant. |
Grantee | A container holding information about to whom an access grant is applied. If it applies to an individual account (that is, the bucket’s owner) it will contain ID and Owner elements. If the grant applies to a group (that is, AllUsers) it will contain a URI element. |
URI | A URI specifying a group of users. At this time, only http://acs.amazonaws.com/groups/global/AllUsers is supported. |
Permission | The level of access granted. At this time, the only supported values are FULL_CONTROL and READ . |
To modify a bucket’s Access Control List, send a PUT
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?acl
The body of the request should include an XML element named AccessControlPolicy
containing information about the ACLs to be applied to the bucket.
Name | Description |
---|---|
Owner | A container holding elements with information about the bucket’s owner. |
ID | An element containing the ID of the bucket’s owner as its value. |
AccessControlList | A container holding a list of elements describing one or more access grants. |
Grant | A container for an individual access grant. |
Grantee | A container holding information about to whom an access grant is applied. If it applies to an individual account (that is, the bucket’s owner) it will contain ID and Owner elements. If the grant applies to a group (that is, AllUsers) it will contain a URI element. |
URI | A URI specifying a group of users. At this time, only http://acs.amazonaws.com/groups/global/AllUsers is supported. |
Permission | The level of access granted. At this time, the only supported values are FULL_CONTROL and READ . |
To retrieve a bucket’s Cross-Origin Resource Sharing (CORS) configuration, send a GET
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?cors
The body of the response includes an XML element named CORSConfiguration
containing information about how the bucket is configured to handle cross-origin requests.
Name | Description |
---|---|
CORSRule |
A container holding a list of elements describing allowed methods for a specific origin. |
AllowedMethod |
An individual HTTP method (for example, GET ) which is allowed from the specified origin. |
AllowedOrigin |
A host from which requests using the specified methods are allowed. It may contain one wildcard (for example, http://*.example.com ). |
AllowedHeader |
A header that will be included in the CORS preflight request’s Access-Control-Request-Headers . It may contain one wildcard (for example, x-amz-* ). |
To configure Cross-Origin Resource Sharing (CORS) for a bucket, send a PUT
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?cors
The body of the request should include an XML element named CORSConfiguration
containing the desired configuration information for handling cross-origin requests.
Name | Description |
---|---|
CORSRule |
A container holding a list of elements describing allowed methods for a specific origin. |
AllowedMethod |
An individual HTTP method (for example, GET ) which is allowed from the specified origin. |
AllowedOrigin |
A host from which requests using the specified methods are allowed. It may contain one wildcard (for example, http://*.example.com ). |
AllowedHeader |
A header that will be included in the CORS preflight request’s Access-Control-Request-Headers . It may contain one wildcard (for example,x-amz-* ). |
To delete a bucket’s Cross-Origin Resource Sharing (CORS) configuration, send a DELETE
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?cors
Success is indicated by receiving 204 (No Content) as the response code.
To retrieve a information about the lifecycle rules configured for a Space, send a GET
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?lifecycle
The body of the response will include an XML element named LifecycleConfiguration
containing a list of Rule
objects.
Name | Description |
---|---|
Rule |
A container holding elements with information about a singe lifecycle rule. |
ID |
A unique string identifying the rule. It may contain up to 255 characters including spaces. |
Status |
A string that specifies whether or not the lifecycle rule will be acted upon. The only valid values are Enabled or Disabled . |
Prefix |
A string specifying the objects to which the rule will be applied. When provided, only objects whose keys begin with the prefix will be acted upon. If empty or not present, all object in the Space will be affected. |
Expiration |
When present, matching objects are expired and automatically deleted. This container specifies either a Date or Days element. |
Days |
An integer specifying the number of days after an object’s creation until the rule takes effect. |
Date |
A date in ISO 8601 format specifying the day that the rule takes effect. The action will be run at midnight UTC. |
AbortIncompleteMultipartUpload |
When present, incomplete multipart uploads of matching objects will be removed. This container specifies a DaysAfterInitiation element. |
DaysAfterInitiation |
An integer specifying the number of days after an incomplete multipart upload was initiated until the rule takes effect. |
Lifecycle rules can be used to perform different actions on objects in a Space over the course of their “life.” For example, a Space may be configured so that objects in it expire and are automatically deleted after a certain length of time. Lifecycle rules based on tagging are not supported.
In order to configure new lifecycle rules, send a PUT
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?lifecycle
The body of the request should include an XML element named LifecycleConfiguration
containing a list of Rule
objects.
Name | Description | Required |
---|---|---|
Rule |
A container holding elements with information about a singe lifecycle rule. | Yes |
ID |
A unique string identifying the rule. It may contain up to 255 characters including spaces. | Yes |
Status |
A string that specifies whether or not the lifecycle rule will be acted upon. The only valid values are Enabled or Disabled. | Yes |
Prefix |
A string specifying the objects to which the rule will be applied. When provided, only objects whose keys begin with the prefix will be acted upon. If empty or not present, all object in the Space will be affected. | No |
Expiration |
When present, matching objects are expired and automatically deleted. This container must specify either a Date or Days element. | No |
Days |
An integer specifying the number of days after an object’s creation until the rule takes effect. | No |
Date |
A date in ISO 8601 format specifying the day that the rule takes effect. The action will be run at midnight UTC. | No |
AbortIncompleteMultipartUpload |
When present, incomplete multipart uploads of matching objects will be removed. This container must specify a DaysAfterInitiation element. | No |
DaysAfterInitiation |
An integer specifying the number of days after an incomplete multipart upload was initiated until the rule takes effect. | No |
To delete a bucket’s lifecycle configuration, send a DELETE
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/?lifecycle
Success is indicated by receiving 204 (No Content) as the response code.
Objects consist of data, such as image files or applications, that you can upload to buckets. The following methods allow you to upload, delete, and manage objects across your buckets.
To retrieve an object from a bucket, send a GET
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}
The body of the response contains the object itself.
To retrieve information about a specific object, send a HEAD
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}
The response will include headers with information about the object (for example, Content-Type
, Content-Length
, Last-Modified
, Etag
) but not the object itself. (See Common Headers for more information about the included information.)
To upload an object to a bucket, send a PUT
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}
The body of the request should contain the object itself. In addition to the common headers used in requests, a number of additional headers are supported:
Name | Description | Required |
---|---|---|
Content-Length |
The length in bytes of the request body. | Yes |
Cache-Control |
Directives used for specifying caching behavior (for example, max-age). | No |
Content-Encoding |
Specifies how and if an object has been compressed for transit (for example, gzip), and thus how the client should decode it in order to obtain the media-type referenced by the Content-Type. | No |
Content-Disposition |
Specifies how the object is expected to be displayed (for example, inline or attachment). | No |
x-amz-acl |
A canned ACL specifying access rules for the object (for example, private or public-read). If not set, defaults to private. | No |
x-amz-storage-class |
Allowed for compatibility purposes. Spaces only accepts the default value, STANDARD , and will reject other, unsupported storage class values. |
No |
x-amz-meta-* |
Prefix used to supply arbitrary user defined metadata (for example, x-amz-meta-file-attrs: uid:1000/gname:username/uname:username/gid:1000/mode:33204). The value may not be larger than 2 KB in size. | No |
Spaces does not support some object copying use cases:
To copy an object from one bucket to another, send a PUT
request to ${DESTINATION_BUCKET}.${REGION}.digitaloceanspaces.com/${DESTINATION_OBJECT_KEY}
In addition to the common headers used in requests, a number of additional headers are required:
Name | Description | Required |
---|---|---|
x-amz-copy-source | Specifies the original object to be copied (for example, /${ORIGIN_BUCKET}/{$ORIGIN_OBJECT_KEY} ). |
Yes |
x-amz-metadata-directive | Indicates whether to copy the object’s metadata or to replace it with values specified in the request. The only valid values are COPY or REPLACE . |
|x-amz-acl|A “canned” ACL specifying access rules for the object (for example, private
or public-read
). If not set, defaults to private.|No|
The body of the response includes an XML element named CopyObjectResult
containing:
Name | Description |
---|---|
LastModified | The date and time that the object was last modified in the format: %Y-%m-%dT%H:%M:%S.%3NZ (for example, 2017-06-23T18:37:48.157Z) |
ETag | The entity tag containing an MD5 hash of the object. |
To retrieve a object’s Access Control List, send a GET
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}?acl
The body of the response includes an XML element named AccessControlPolicy
containing information about the ACLs applied to the object.
Name | Description |
---|---|
Owner | A container holding elements with information about the object’s owner. |
ID | An element containing the ID of the object’s owner as its value. |
DisplayName | An element containing the DisplayName of the object’s owner as its value. Provided for compatibility purposes, has the same value as the ID. |
AccessControlList | A container holding a list of elements describing one or more access grants. |
Grant | A container for an individual access grant. |
Grantee | A container holding information about to whom an access grant is applied. If it applies to an individual account (that is, the object’s owner) it will contain ID and Owner elements. If the grant applies to a group (that is, AllUsers) it will contain a URI element. |
URI | A URI specifying a group of users. At this time, only http://acs.amazonaws.com/groups/global/AllUsers is supported. |
Permission | The level of access granted. At this time, the only supported values are FULL_CONTROL and READ . |
To modify an object’s Access Control List, send a PUT
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}?acl
The body of the request should include an XML element named AccessControlPolicy
containing information about the ACLs to be applied to the object.
Name | Description |
---|---|
Owner | A container holding elements with information about the object’s owner. |
ID | An element containing the ID of the object’s owner as its value. |
AccessControlList | A container holding a list of elements describing one or more access grants. |
Grant | A container for an individual access grant. |
Grantee | A container holding information about to whom an access grant is applied. If it applies to an individual account (that is, the object’s owner) it will contain ID and Owner elements. If the grant applies to a group (that is, AllUsers) it will contain a URI element. |
URI | A URI specifying a group of users. At this time, only http://acs.amazonaws.com/groups/global/AllUsers is supported. |
Permission | The level of access granted. At this time, the only supported values are FULL_CONTROL and READ . |
To delete an object, send a DELETE
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}
Success is indicated by receiving 204 (No Content) as the response code.
To initiate a multi-part upload session, send a POST
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}?uploads
In addition to the common headers used in requests, a number of additional headers are supported:
Name | Description | Required |
---|---|---|
Cache-Control | Directives used for specifying caching behavior (for example, max-age ). |
No |
Content-Encoding | Specifies how and if an object has been compressed for transit (for example, gzip ), and thus how the client should decode it in order to obtain the media-type referenced by the Content-Type . |
No |
Content-Disposition | Specifies how the object is expected to be displayed (for example, inline or attachment ). |
No |
x-amz-acl | A “canned” ACL specifying access rules for the object (for example, private or public-read ). If not set, defaults to private . |
No |
x-amz-meta-* | Prefix used to supply arbitrary user defined metadata (for example, x-amz-meta-file-attrs: uid:1000/gname:username/uname:username/gid:1000/mode:33204 ). The value may not be larger than 2 KB in size. |
No |
The body of the response will include an XML element named InitiateMultipartUploadResult
containing the UploadId
used to identify the multi-part upload session in any following requests.
Name | Description |
---|---|
Bucket | The name of the bucket. |
Key | The object’s key. |
UploadId | The unique identifier for the multi-part upload session. |
To retrieve a list of in-progress multipart uploads, send a GET
request to ${BUCKET}.${REGION}.digitaloceanspaces.com?uploads&max-uploads=${MAX_UPLOADS}
where ${MAX_UPLOADS}
is the maximum number of in-progress uploads to return.
Name | Description | Required |
---|---|---|
Bucket | The name of the bucket. | Yes |
delimiter | A single character used to group keys. When specified, the response will only contain keys up to its first occurrence. (for example, using a slash as the delimiter can allow you to list keys as if they were folders, especially in combination with a prefix .) |
No |
encoding-type | Encodes the object keys in the response and specifies the encoding method to use. Valid Values: url |
No |
key-marker | Used with the upload-id marker, you can specify where in the list of current uploads to begin returning results. You can page through the results by updating this parameter in subsequent requests. |
No |
max-uploads | The maximum number of multipart uploads to return in the response. Valid values are integer of 1 to 1000 . |
Yes |
prefix | A string used to group keys. | No |
upload-id-marker | Used with the key-marker , you can specify after which upload the return list should begin. If you don’t specify a key-marker the the upload-id-marker parameter is ignored. |
No |
The body of the response includes an XML element named ListMultipartUploadsResult
containing the UploadId
used to identify the multi-part upload session in any following requests. In-progress uploads are sorted by object key and in ascending order within each key.
Name | Description |
---|---|
ListMultipartUploadsResult | Root level tag for the ListMultipartUploadsResult parameters. |
Bucket | Name of the bucket being uploaded to. |
CommonPrefixes | An array of key prefixes containing the delimiter specified in the request. |
Delimiter | The delimiter specified in the requests. |
EncodingType | If you specify encoding-type , the API returns encoded key name values in the following response elements: Delimiter , KeyMarker , Prefix , NextKeyMarker , Key . |
IsTruncated | Indicates if the returned list of multipart uploads has been truncated. |
KeyMarker | The key at or after which the listing began. |
MaxUploads | The maximum number of upload that could have been returned in a response. This can be changed with the request by changing the values of the max-uploads parameter. |
NextKeyMarker | When a list is truncated, you can page through the results by the applying the value of NextKeyMarker to the key-marker request parameter in a subsequent request. |
NextUploadIdMarker | When a list is truncated, you can page through the results by the applying the value of NextUploadIdMarker to the upload-id-marker request parameter in a subsequent request. |
Prefix | The optional prefix value specified in the request. |
Upload | An array of the properties about the upload. |
Upload Marker | The upload ID after which listing began. |
To upload part of an object in a multi-part upload session, send a PUT
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}?partNumber=${PART_NUMBER}&uploadId=${UPLOAD_ID}
.
The ${PART_NUMBER}
specifies which piece of the object is included in the upload. The ${UPLOAD_ID}
is the unique identifier returned when the multi-part upload session was initiated. The body of the request should contain the piece of the object.
To list the parts of a multi-part upload session, send a GET
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}?uploadId=${UPLOAD_ID}
where ${UPLOAD_ID}
is the unique identifier returned when the multi-part upload session was initiated.
The body of the response contains an XML element named ListPartsResult
containing information about the multi-part upload session and a list of XML objects representing each part of the upload:
Name | Description |
---|---|
Bucket | The name of the bucket. |
Key | The object’s key. |
UploadId | The unique identifier returned when the multi-part upload session was initiated. |
StorageClass | Provided for compatibility purposes. The value is always STANDARD . |
PartNumberMarker | The part number where the list begins. |
NextPartNumberMarker | When the list is truncated, specifies the part number indicating where the next response begins. |
MaxParts | The maximum number of parts to return. Defaults to 1,000. |
IsTruncated | A boolean indicating whether all parts are included in the response. |
Part | A container holding elements with information about the parts of the multi-part upload. |
PartNumber | A sequential identifier specifying the part of the object. |
LastModified | The date and time that the part of the object was last modified in the format: %Y-%m-%dT%H:%M:%S.%3NZ (for example, 2017-06-23T18:37:48.157Z ) |
ETag | The entity tag containing an MD5 hash of the part of the object. |
Size | The size of the part of the object in bytes. |
Owner | A container holding elements with information about the bucket’s owner. |
ID | An element containing the ID of the bucket’s owner as its value. |
DisplayName | An element containing the DisplayName of the bucket’s owner as its value. Provided for compatibility purposes, has the same value as the ID. |
To complete a multi-part upload session, send a POST
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}?uploadId=${UPLOAD_ID}
where ${UPLOAD_ID}
is the unique identifier returned when the multi-part upload session was initiated.
The body of the request should include an XML element named CompleteMultipartUpload
containing information about each of the parts of the upload:
Name | Description | Required |
---|---|---|
Part | A container holding elements with information about an individual part of a multi-part upload. | Yes |
PartNumber | A sequential identifier specifying the part of the object. | Yes |
ETag | The entity tag containing an MD5 hash of the part of the object. | Yes |
The body of the response includes an XML element named CompleteMultipartUploadResult
containing information about the completed upload:
Name | Description |
---|---|
Location | The location of the bucket. |
Bucket | The name of the bucket. |
Key | The object’s key. |
ETag | The entity tag containing an MD5 hash of the final object. |
To cancel an active multi-part upload session, send a DELETE
request to ${BUCKET}.${REGION}.digitaloceanspaces.com/${OBJECT_KEY}?uploadId=${UPLOAD_ID}
where ${UPLOAD_ID}
is the unique identifier returned when the multi-part upload session was initiated.
Success is indicated by receiving 204 (No Content) as the response code.