[ceph.git] / ceph / doc / radosgw / swift / containerops.rst

======================
 Container Operations
======================

A container is a mechanism for storing data objects. An account may
have many containers, but container names must be unique. This API enables a 
client to create a container, set access controls and metadata, 
retrieve a container's contents, and delete a container. Since this API 
makes requests related to information in a particular user's account, all 
requests in this API must be authenticated unless a container's access control
is deliberately made publicly accessible (i.e., allows anonymous requests).

.. note:: The Amazon S3 API uses the term 'bucket' to describe a data container.
   When you hear someone refer to a 'bucket' within the Swift API, the term 
   'bucket' may be construed as the equivalent of the term 'container.'
   
One facet of object storage is that it does not support hierarchical paths
or directories. Instead, it supports one level consisting of one or more
containers, where each container may have objects. The RADOS Gateway's
Swift-compatible API supports the notion of 'pseudo-hierarchical containers,'
which is a means of using object naming to emulate a container (or directory)
hierarchy without actually implementing one in the storage system. You may 
name objects with pseudo-hierarchical names 
(e.g., photos/buildings/empire-state.jpg), but container names cannot
contain a forward slash (``/``) character.


Create a Container
==================

To create a new container, make a ``PUT`` request with the API version, account,
and the name of the new container. The container name must be unique, must not
contain a forward-slash (/) character, and should be less than 256 bytes. You 
may include access control headers and metadata headers in the request. The 
operation is idempotent; that is, if you make a request to create a container
that already exists, it will return with a HTTP 202 return code, but will not
create another container.


Syntax
~~~~~~

::

	PUT /{api version}/{account}/{container} HTTP/1.1
	Host: {fqdn}
	X-Auth-Token: {auth-token}
	X-Container-Read: {comma-separated-uids}
	X-Container-Write: {comma-separated-uids}
	X-Container-Meta-{key}: {value}


Headers
~~~~~~~

``X-Container-Read``

:Description: The user IDs with read permissions for the container. 
:Type: Comma-separated string values of user IDs.
:Required: No

``X-Container-Write``

:Description: The user IDs with write permissions for the container.
:Type: Comma-separated string values of user IDs.
:Required: No

``X-Container-Meta-{key}``

:Description:  A user-defined meta data key that takes an arbitrary string value.
:Type: String
:Required: No


HTTP Response
~~~~~~~~~~~~~

If a container with the same name already exists, and the user is the
container owner then the operation will succeed. Otherwise the operation
will fail.

``409``

:Description: The container already exists under a different user's ownership.
:Status Code: ``BucketAlreadyExists``


List a Container's Objects
==========================

To list the objects within a container, make a ``GET`` request with the with the 
API version, account, and the name of the container.  You can specify query 
parameters to filter the full list, or leave out the parameters to return a list 
of the first 10,000 object names stored in the container.


Syntax
~~~~~~

::

   GET /{api version}/{container} HTTP/1.1
  	Host: {fqdn}
	X-Auth-Token: {auth-token}


Parameters
~~~~~~~~~~

``format``

:Description: Defines the format of the result. 
:Type: String
:Valid Values: ``json`` | ``xml``
:Required: No

``prefix``

:Description: Limits the result set to objects beginning with the specified prefix.
:Type: String
:Required: No

``marker``

:Description: Returns a list of results greater than the marker value.
:Type: String
:Required: No

``limit``

:Description: Limits the number of results to the specified value.
:Type: Integer
:Valid Range: 0 - 10,000
:Required: No

``delimiter``

:Description: The delimiter between the prefix and the rest of the object name.
:Type: String
:Required: No

``path``

:Description: The pseudo-hierarchical path of the objects.
:Type: String
:Required: No

``allow_unordered``

:Description: Allows the results to be returned unordered to reduce computation overhead. Cannot be used with ``delimiter``.
:Type: Boolean
:Required: No
:Non-Standard Extension: Yes


Response Entities
~~~~~~~~~~~~~~~~~

``container``

:Description: The container. 
:Type: Container

``object``

:Description: An object within the container.
:Type: Container

``name``

:Description: The name of an object within the container.
:Type: String

``hash``

:Description: A hash code of the object's contents.
:Type: String

``last_modified``

:Description: The last time the object's contents were modified.
:Type: Date

``content_type``

:Description: The type of content within the object.
:Type: String


Update a Container's ACLs
=========================

When a user creates a container, the user has read and write access to the
container by default. To allow other users to read a container's contents or
write to a container, you must specifically enable the user. 
You may also specify ``*`` in the ``X-Container-Read`` or ``X-Container-Write``
settings, which effectively enables all users to either read from or write
to the container. Setting ``*`` makes the container public. That is it 
enables anonymous users to either read from or write to the container.

.. note:: If you are planning to expose public read ACL functionality
	  for the Swift API, it is strongly recommended to include the
	  Swift account name in the endpoint definition, so as to most
	  closely emulate the behavior of native OpenStack Swift. To
	  do so, set the ``ceph.conf`` configuration option ``rgw
	  swift account in url = true``, and update your Keystone
	  endpoint to the URL suffix ``/v1/AUTH_%(tenant_id)s``
	  (instead of just ``/v1``).


Syntax
~~~~~~

::

   POST /{api version}/{account}/{container} HTTP/1.1
   Host: {fqdn}
	X-Auth-Token: {auth-token}
	X-Container-Read: *
	X-Container-Write: {uid1}, {uid2}, {uid3}

Request Headers
~~~~~~~~~~~~~~~

``X-Container-Read``

:Description: The user IDs with read permissions for the container. 
:Type: Comma-separated string values of user IDs.
:Required: No

``X-Container-Write``

:Description: The user IDs with write permissions for the container.
:Type: Comma-separated string values of user IDs.
:Required: No


Add/Update Container Metadata
=============================

To add metadata to a container, make a ``POST`` request with the API version, 
account, and container name. You must have write permissions on the 
container to add or update metadata.

Syntax
~~~~~~

::

   POST /{api version}/{account}/{container} HTTP/1.1
   Host: {fqdn}
	X-Auth-Token: {auth-token}
	X-Container-Meta-Color: red
	X-Container-Meta-Taste: salty
	
Request Headers
~~~~~~~~~~~~~~~

``X-Container-Meta-{key}``

:Description:  A user-defined meta data key that takes an arbitrary string value.
:Type: String
:Required: No


Enable Object Versioning for a Container
========================================

To enable object versioning a container, make a ``POST`` request with
the API version, account, and container name. You must have write
permissions on the container to add or update metadata.

.. note:: Object versioning support is not enabled in radosgw by
	  default; you must set ``rgw swift versioning enabled =
	  true`` in ``ceph.conf`` to enable this feature.

Syntax
~~~~~~

::

   POST /{api version}/{account}/{container} HTTP/1.1
   Host: {fqdn}
	X-Auth-Token: {auth-token}
	X-Versions-Location: {archive-container}

Request Headers
~~~~~~~~~~~~~~~

``X-Versions-Location``

:Description: The name of a container (the "archive container") that
	      will be used to store versions of the objects in the
	      container that the ``POST`` request is made on (the
	      "current container"). The archive container need not
	      exist at the time it is being referenced, but once
	      ``X-Versions-Location`` is set on the current container,
	      and object versioning is thus enabled, the archive
	      container must exist before any further objects are
	      updated or deleted in the current container.

	      .. note:: ``X-Versions-Location`` is the only
                        versioning-related header that radosgw
                        interprets. ``X-History-Location``, supported
                        by native OpenStack Swift, is currently not
                        supported by radosgw.
:Type: String
:Required: No (if this header is passed with an empty value, object
	   versioning on the current container is disabled, but the
	   archive container continues to exist.)


Delete a Container
==================

To delete a container, make a ``DELETE`` request with the API version, account,
and the name of the container. The container must be empty. If you'd like to check 
if the container is empty, execute a ``HEAD`` request against the container. Once 
you have successfully removed the container, you will be able to reuse the container name.

Syntax
~~~~~~

::

	DELETE /{api version}/{account}/{container} HTTP/1.1
	Host: {fqdn}
	X-Auth-Token: {auth-token}    


HTTP Response
~~~~~~~~~~~~~

``204``

:Description: The container was removed.
:Status Code: ``NoContent``
Commit	Line	Data
7c673cae FG	1	======================
	2	Container Operations
	3	======================
	4
	5	A container is a mechanism for storing data objects. An account may
	6	have many containers, but container names must be unique. This API enables a
	7	client to create a container, set access controls and metadata,
	8	retrieve a container's contents, and delete a container. Since this API
	9	makes requests related to information in a particular user's account, all
	10	requests in this API must be authenticated unless a container's access control
	11	is deliberately made publicly accessible (i.e., allows anonymous requests).
	12
	13	.. note:: The Amazon S3 API uses the term 'bucket' to describe a data container.
	14	When you hear someone refer to a 'bucket' within the Swift API, the term
	15	'bucket' may be construed as the equivalent of the term 'container.'
	16
	17	One facet of object storage is that it does not support hierarchical paths
	18	or directories. Instead, it supports one level consisting of one or more
	19	containers, where each container may have objects. The RADOS Gateway's
	20	Swift-compatible API supports the notion of 'pseudo-hierarchical containers,'
	21	which is a means of using object naming to emulate a container (or directory)
	22	hierarchy without actually implementing one in the storage system. You may
	23	name objects with pseudo-hierarchical names
	24	(e.g., photos/buildings/empire-state.jpg), but container names cannot
	25	contain a forward slash (``/``) character.
	26
	27
	28	Create a Container
	29	==================
	30
	31	To create a new container, make a ``PUT`` request with the API version, account,
	32	and the name of the new container. The container name must be unique, must not
	33	contain a forward-slash (/) character, and should be less than 256 bytes. You
	34	may include access control headers and metadata headers in the request. The
	35	operation is idempotent; that is, if you make a request to create a container
	36	that already exists, it will return with a HTTP 202 return code, but will not
	37	create another container.
	38
	39
	40	Syntax
	41	~~~~~~
	42
	43	::
	44
	45	PUT /{api version}/{account}/{container} HTTP/1.1
	46	Host: {fqdn}
	47	X-Auth-Token: {auth-token}
	48	X-Container-Read: {comma-separated-uids}
	49	X-Container-Write: {comma-separated-uids}
	50	X-Container-Meta-{key}: {value}
	51
	52
	53	Headers
	54	~~~~~~~
	55
	56	``X-Container-Read``
	57
	58	:Description: The user IDs with read permissions for the container.
	59	:Type: Comma-separated string values of user IDs.
	60	:Required: No
	61
	62	``X-Container-Write``
	63
	64	:Description: The user IDs with write permissions for the container.
65	:Type: Comma-separated string values of user IDs.
66	:Required: No
67
68	``X-Container-Meta-{key}``
69
70	:Description: A user-defined meta data key that takes an arbitrary string value.
71	:Type: String
72	:Required: No
73
74
75	HTTP Response
76	~~~~~~~~~~~~~
77
78	If a container with the same name already exists, and the user is the
79	container owner then the operation will succeed. Otherwise the operation
80	will fail.
81
82	``409``
83
84	:Description: The container already exists under a different user's ownership.
85	:Status Code: ``BucketAlreadyExists``
86
87
88
89
90	List a Container's Objects
91	==========================
92
93	To list the objects within a container, make a ``GET`` request with the with the
94	API version, account, and the name of the container. You can specify query
95	parameters to filter the full list, or leave out the parameters to return a list
96	of the first 10,000 object names stored in the container.
97
98
99	Syntax
100	~~~~~~
101
102	::
103
104	GET /{api version}/{container} HTTP/1.1
105	Host: {fqdn}
106	X-Auth-Token: {auth-token}
107
108
109	Parameters
110	~~~~~~~~~~
111
112	``format``
113
114	:Description: Defines the format of the result.
115	:Type: String
116	:Valid Values: ``json`` \| ``xml``
117	:Required: No
118
119	``prefix``
120
121	:Description: Limits the result set to objects beginning with the specified prefix.
122	:Type: String
123	:Required: No
124
125	``marker``
126
127	:Description: Returns a list of results greater than the marker value.
128	:Type: String
129	:Required: No
130
131	``limit``
132
133	:Description: Limits the number of results to the specified value.
134	:Type: Integer
135	:Valid Range: 0 - 10,000
136	:Required: No
137
138	``delimiter``
139
140	:Description: The delimiter between the prefix and the rest of the object name.
141	:Type: String
142	:Required: No
143
144	``path``
145
146	:Description: The pseudo-hierarchical path of the objects.
147	:Type: String
148	:Required: No
149
1adf2230 AA	150	``allow_unordered``
	151
	152	:Description: Allows the results to be returned unordered to reduce computation overhead. Cannot be used with ``delimiter``.
	153	:Type: Boolean
	154	:Required: No
	155	:Non-Standard Extension: Yes
	156
7c673cae FG	157
	158	Response Entities
	159	~~~~~~~~~~~~~~~~~
	160
	161	``container``
	162
	163	:Description: The container.
	164	:Type: Container
	165
	166	``object``
	167
	168	:Description: An object within the container.
	169	:Type: Container
	170
	171	``name``
	172
	173	:Description: The name of an object within the container.
	174	:Type: String
	175
	176	``hash``
	177
	178	:Description: A hash code of the object's contents.
	179	:Type: String
	180
	181	``last_modified``
	182
	183	:Description: The last time the object's contents were modified.
	184	:Type: Date
	185
	186	``content_type``
	187
	188	:Description: The type of content within the object.
	189	:Type: String
	190
	191
	192
	193	Update a Container's ACLs
	194	=========================
	195
	196	When a user creates a container, the user has read and write access to the
	197	container by default. To allow other users to read a container's contents or
	198	write to a container, you must specifically enable the user.
	199	You may also specify ``*`` in the ``X-Container-Read`` or ``X-Container-Write``
	200	settings, which effectively enables all users to either read from or write
	201	to the container. Setting ``*`` makes the container public. That is it
	202	enables anonymous users to either read from or write to the container.
	203
11fdf7f2 TL	204	.. note:: If you are planning to expose public read ACL functionality
	205	for the Swift API, it is strongly recommended to include the
	206	Swift account name in the endpoint definition, so as to most
	207	closely emulate the behavior of native OpenStack Swift. To
	208	do so, set the ``ceph.conf`` configuration option ``rgw
	209	swift account in url = true``, and update your Keystone
	210	endpoint to the URL suffix ``/v1/AUTH_%(tenant_id)s``
	211	(instead of just ``/v1``).
	212
7c673cae FG	213
	214	Syntax
	215	~~~~~~
	216
	217	::
	218
	219	POST /{api version}/{account}/{container} HTTP/1.1
	220	Host: {fqdn}
	221	X-Auth-Token: {auth-token}
	222	X-Container-Read: *
	223	X-Container-Write: {uid1}, {uid2}, {uid3}
	224
	225	Request Headers
	226	~~~~~~~~~~~~~~~
	227
	228	``X-Container-Read``
	229
	230	:Description: The user IDs with read permissions for the container.
	231	:Type: Comma-separated string values of user IDs.
	232	:Required: No
	233
	234	``X-Container-Write``
	235
	236	:Description: The user IDs with write permissions for the container.
	237	:Type: Comma-separated string values of user IDs.
	238	:Required: No
	239
	240
	241	Add/Update Container Metadata
	242	=============================
	243
	244	To add metadata to a container, make a ``POST`` request with the API version,
	245	account, and container name. You must have write permissions on the
	246	container to add or update metadata.
	247
	248	Syntax
	249	~~~~~~
	250
	251	::
	252
	253	POST /{api version}/{account}/{container} HTTP/1.1
	254	Host: {fqdn}
	255	X-Auth-Token: {auth-token}
	256	X-Container-Meta-Color: red
	257	X-Container-Meta-Taste: salty
	258
	259	Request Headers
	260	~~~~~~~~~~~~~~~
	261
	262	``X-Container-Meta-{key}``
	263
	264	:Description: A user-defined meta data key that takes an arbitrary string value.
	265	:Type: String
	266	:Required: No
	267
	268
11fdf7f2 TL	269	Enable Object Versioning for a Container
	270	========================================
	271
	272	To enable object versioning a container, make a ``POST`` request with
	273	the API version, account, and container name. You must have write
	274	permissions on the container to add or update metadata.
	275
	276	.. note:: Object versioning support is not enabled in radosgw by
	277	default; you must set ``rgw swift versioning enabled =
	278	true`` in ``ceph.conf`` to enable this feature.
	279
	280	Syntax
	281	~~~~~~
	282
	283	::
	284
	285	POST /{api version}/{account}/{container} HTTP/1.1
	286	Host: {fqdn}
	287	X-Auth-Token: {auth-token}
	288	X-Versions-Location: {archive-container}
	289
	290	Request Headers
	291	~~~~~~~~~~~~~~~
	292
	293	``X-Versions-Location``
	294
	295	:Description: The name of a container (the "archive container") that
	296	will be used to store versions of the objects in the
	297	container that the ``POST`` request is made on (the
	298	"current container"). The archive container need not
	299	exist at the time it is being referenced, but once
	300	``X-Versions-Location`` is set on the current container,
	301	and object versioning is thus enabled, the archive
	302	container must exist before any further objects are
	303	updated or deleted in the current container.
	304
	305	.. note:: ``X-Versions-Location`` is the only
	306	versioning-related header that radosgw
	307	interprets. ``X-History-Location``, supported
	308	by native OpenStack Swift, is currently not
	309	supported by radosgw.
	310	:Type: String
	311	:Required: No (if this header is passed with an empty value, object
	312	versioning on the current container is disabled, but the
	313	archive container continues to exist.)
	314
7c673cae FG	315
	316	Delete a Container
	317	==================
	318
	319	To delete a container, make a ``DELETE`` request with the API version, account,
	320	and the name of the container. The container must be empty. If you'd like to check
	321	if the container is empty, execute a ``HEAD`` request against the container. Once
c07f9fc5	322	you have successfully removed the container, you will be able to reuse the container name.
7c673cae FG	323
	324	Syntax
	325	~~~~~~
	326
	327	::
	328
	329	DELETE /{api version}/{account}/{container} HTTP/1.1
	330	Host: {fqdn}
	331	X-Auth-Token: {auth-token}
	332
	333
	334	HTTP Response
	335	~~~~~~~~~~~~~
	336
	337	``204``
	338
	339	:Description: The container was removed.
	340	:Status Code: ``NoContent``
	341