REST API for Standard Storage in Oracle Cloud Infrastructure Object Storage Classic

Show account details and list containers

get

/v1/{account}

Shows details for an account and lists containers, sorted by name, in the account.

Request

Path Parameters

account: string

The unique name for the account. An account is also known as the project or tenant.

Query Parameters

delimiter(optional): string(char)

Delimiter value, which returns the object names that are nested in the container.
end_marker(optional): string

For a string value, x, returns container names that are less than the marker value.
format(optional): string

The response format. Valid values are json, xml, or plain. The default is plain.
If you append the format=xml or format=json query parameter to the storage account URL, the response shows extended container information serialized in that format.
If you append the format=plain query parameter, the response lists the container names separated by newlines.

Default Value: plain

Allowed Values: [ "json", "xml", "plain" ]
limit(optional): integer

For an integer value n, limits the number of results to n. Any negative value will be equivalent to 0: no items will be returned.
marker(optional): string

For a string value, x, returns container names that are greater than the marker value.
prefix(optional): string

Prefix value. Named items in the response begin with this value.

Header Parameters

Accept(optional): string

Instead of using the format query parameter, set this header to application/json, application/xml, or text/plain.
X-Auth-Token: string

Authentication token.
X-Newest(optional): boolean

If set to true, Object Storage queries all replicas to return the most recent one. If you omit this header, Object Storage responds faster after it finds one valid replica. Because setting this header to true is more expensive for the back end, use it only when it is absolutely needed.

Response

Supported Media Types

application/json

200 Response

Success. The response body lists the containers.

Headers

Content-Length: integer

Minimum Value: 0

The length of the response body that contains the list of names. If the operation fails, this value is the length of the error text in the response body.
Content-Type: string

The MIME type of the list of names. If the operation fails, this value is the MIME type of the error text in the response body.
Date: string(date-time)
The transaction date and time.
The date and time stamp format is ISO 8601:
```
CCYY-MM-DDThh:mm:ss±hh:mm
```
For example, 2015-08-27T09:49:58-05:00.
The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
A null value indicates that the token never expires.
X-Account-Bytes-Used: integer

Minimum Value: 0

The total number of bytes that are stored in Object Storage for the account.
X-Account-Container-Count: integer

Minimum Value: 0

The number of containers.
X-Account-Meta-Temp-URL-Key: string

(Optional) The secret key value for temporary URLs. If not set, this header is not returned in the response.
X-Account-Meta-Temp-URL-Key-2: string

(Optional) A second secret key value for temporary URLs. If not set, this header is not returned in the response.
X-Account-Meta-name: string

(Optional) The custom account metadata item, where {name} is the name of the metadata item.
One X-Account-Meta-{name} response header appears for each metadata item (for each {name}).
X-Account-Object-Count: integer

Minimum Value: 0

The number of objects in the account.
X-Timestamp: integer(timestamp)

Minimum Value: 0

The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version.
For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
X-Trans-Id: string(uuid)

A unique transaction identifier for this request. Your service provider might need this value if you report a problem.

Root Schema : schema

Type: array

Show Source

Array of: object items

{
    "type":"array",
    "items":{
        "type":"object",
        "properties":{
            "count":{
                "type":"integer",
                "description":"The number of objects in the container.",
                "minimum":0
            },
            "bytes":{
                "type":"integer",
                "description":"The total number of bytes that are stored in Object Storage for the account.",
                "minimum":0
            },
            "name":{
                "type":"string",
                "description":"The name of the container."
            }
        }
    }
}

Nested Schema : items

Type: object

Show Source

bytes(optional): integer

Minimum Value: 0

The total number of bytes that are stored in Object Storage for the account.
count(optional): integer

Minimum Value: 0

The number of objects in the container.
name(optional): string

The name of the container.

{
    "type":"object",
    "properties":{
        "count":{
            "type":"integer",
            "description":"The number of objects in the container.",
            "minimum":0
        },
        "bytes":{
            "type":"integer",
            "description":"The total number of bytes that are stored in Object Storage for the account.",
            "minimum":0
        },
        "name":{
            "type":"string",
            "description":"The name of the container."
        }
    }
}

204 Response

Success. The response body shows no containers. Either the account has no containers or you are paging through a long list of names by using the marker, limit, or end_marker query parameter and you have reached the end of the list.

Headers

Content-Length: integer

Minimum Value: 0

The length of the response body that contains the list of names. If the operation fails, this value is the length of the error text in the response body.
Content-Type: string

The MIME type of the list of names. If the operation fails, this value is the MIME type of the error text in the response body.
Date: string(date-time)
The transaction date and time.
The date and time stamp format is ISO 8601:
```
CCYY-MM-DDThh:mm:ss±hh:mm
```
For example, 2015-08-27T09:49:58-05:00.
The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.
A null value indicates that the token never expires.
X-Account-Bytes-Used: integer

Minimum Value: 0

The total number of bytes that are stored in Object Storage for the account.
X-Account-Container-Count: integer

Minimum Value: 0

The number of containers.
X-Account-Meta-Temp-URL-Key: string

(Optional) The secret key value for temporary URLs. If not set, this header is not returned in the response.
X-Account-Meta-Temp-URL-Key-2: string

(Optional) A second secret key value for temporary URLs. If not set, this header is not returned in the response.
X-Account-Meta-{name}: string

(Optional) The custom account metadata item, where {name} is the name of the metadata item.
One X-Account-Meta-{name} response header appears for each metadata item (for each {name}).
X-Account-Object-Count: integer

Minimum Value: 0

The number of objects in the account.
X-Timestamp: integer(timestamp)

Minimum Value: 0

The date and time in UNIX Epoch time stamp format when the account, container, or object was initially created as a current version.
For example, 1440619048 is equivalent to Mon, Wed, 26 Aug 2015 19:57:28 GMT.
X-Trans-Id: string(uuid)

A unique transaction identifier for this request. Your service provider might need this value if you report a problem.

401 Response

Request does not include an authentication token, or authentication token specified in the request is not valid. It may have expired. Authentication tokens expire after 30 minutes.

Headers

Content-Length: integer

Minimum Value: 0

The length of the error text in the response body.
Content-Type: string

The MIME type of the error text in the response body.

Examples

cURL Command

Sample Cloud account with the following details:

Account name: acme
REST Endpoint URL: https://acme.storage.oraclecloud.com/v1/Storage-acme
REST Endpoint (Permanent) URL: https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365

Note:

The REST Endpoint (Permanent) URL is displayed for the accounts created after November 2017.

The following example shows how to list the containers, lexicographically sorted, in the specified account in Oracle Cloud Infrastructure Object Storage Classic by submitting a GET request on the REST resource using cURL. For more information about cURL, see Use cURL.

Using the REST Endpoint URL obtained from the REST Endpoint field in the My Services dashboard:

curl -v -X GET \
     -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
     https://acme.storage.oraclecloud.com/v1/Storage-acme

The following is a sample response of this command:

HTTP/1.1 200 OK
Date: Fri, 06 Mar 2015 10:38:15 GMT
Content-Length: 109
X-Account-Container-Count: 3
Accept-Ranges: bytes
X-Account-Object-Count: 843
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx23a1084b8c674fdeae8d4-0054f982ac
X-Account-Bytes-Used: 10304761355
X-Timestamp: 1412823447.62495
X-Account-Meta-Test5: test1
X-Account-Meta-Quota-Bytes: 107374182400
FirstContainer
NewContainer
StorageTest

Using the Service Permanent REST Endpoint URL obtained from the REST Endpoint (Permanent) field in the My Services dashboard:

Note:

This cURL command example applies to the accounts created after November 2017.

curl -v -X GET \
     -H "X-Auth-Token: AUTH_tkb4fdf39c92e9f62cca9b7c196f8b6e6b" \
     https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365

The following is a sample response of this command:

HTTP/1.1 200 OK
Date: Fri, 06 Mar 2015 10:38:15 GMT
Content-Length: 109
X-Account-Container-Count: 3
Accept-Ranges: bytes
X-Account-Object-Count: 843
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx23a1084b8c674fdeae8d4-0054f982ac
X-Account-Bytes-Used: 10304761355
X-Timestamp: 1412823447.62495
X-Account-Meta-Test5: test1
X-Account-Meta-Quota-Bytes: 107374182400
FirstContainer
NewContainer
StorageTest