diff --git a/api-ref/source/conf.py b/api-ref/source/conf.py new file mode 100644 index 0000000000..e01012aeb0 --- /dev/null +++ b/api-ref/source/conf.py @@ -0,0 +1,221 @@ +# -*- coding: utf-8 -*- +# +# Licensed under the Apache License, Version 2.0 (the "License"); you may +# not use this file except in compliance with the License. You may obtain +# a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +# License for the specific language governing permissions and limitations +# under the License. +# +# swift documentation build configuration file +# +# This file is execfile()d with the current directory set to +# its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import os +from swift import __version__ +import subprocess +import sys +import warnings + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +sys.path.insert(0, os.path.abspath('../../')) +sys.path.insert(0, os.path.abspath('../')) +sys.path.insert(0, os.path.abspath('./')) + +# -- General configuration ---------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. + +extensions = [ + 'os_api_ref', + 'oslosphinx', +] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +# +# source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Object Storage API Reference' +copyright = u'2010-present, OpenStack Foundation' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = __version__.rsplit('.', 1)[0] +# The full version, including alpha/beta/rc tags. +release = __version__ + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# today = '' +# Else, today_fmt is used as the format for a strftime call. +# today_fmt = '%B %d, %Y' + +# The reST default role (used for this markup: `text`) to use +# for all documents. +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = False + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- Options for man page output ---------------------------------------------- + +# Grouping the document tree for man pages. +# List of tuples 'sourcefile', 'target', u'title', u'Authors name', 'manual' + + +# -- Options for HTML output -------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +# html_theme_path = ["."] +# html_theme = '_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +# html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +# html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +#html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +# html_last_updated_fmt = '%b %d, %Y' +git_cmd = ["git", "log", "--pretty=format:'%ad, commit %h'", "--date=local", + "-n1"] +try: + html_last_updated_fmt = subprocess.Popen( + git_cmd, stdout=subprocess.PIPE).communicate()[0] +except OSError: + warnings.warn('Cannot get last updated time from git repository. ' + 'Not setting "html_last_updated_fmt".') + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# html_additional_pages = {} + +# If false, no module index is generated. +# html_use_modindex = True + +# If false, no index is generated. +# html_use_index = True + +# If true, the index is split into individual pages for each letter. +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +# html_show_sourcelink = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'swiftdoc' + + +# -- Options for LaTeX output ------------------------------------------------- + +# The paper size ('letter' or 'a4'). +# latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +# latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', 'swift.tex', u'OpenStack Object Storage API Documentation', + u'OpenStack Foundation', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +# latex_preamble = '' + +# Documents to append as an appendix to all manuals. +# latex_appendices = [] + +# If false, no module index is generated. +# latex_use_modindex = True diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst new file mode 100644 index 0000000000..5b4e643f1d --- /dev/null +++ b/api-ref/source/index.rst @@ -0,0 +1,13 @@ +:tocdepth: 2 + +=================== + Object Storage API +=================== + +.. rest_expand_all:: + +.. include:: storage-account-services.inc +.. include:: storage_endpoints.inc +.. include:: storage-object-services.inc +.. include:: storage-container-services.inc +.. include:: storage_info.inc diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml new file mode 100644 index 0000000000..9213ada101 --- /dev/null +++ b/api-ref/source/parameters.yaml @@ -0,0 +1,961 @@ +# variables in header +Accept: + description: | + Instead of using the ``format`` query parameter, + set this header to ``application/json``, ``application/xml``, or + ``text/xml``. + in: header + required: false + type: string +Accept-Ranges: + description: | + The type of ranges that the object accepts. + in: header + required: true + type: string +Content-Disposition: + description: | + If set, specifies the override behavior for the + browser. For example, this header might specify that the browser + use a download program to save this file rather than show the + file, which is the default. + in: header + required: false + type: string +Content-Disposition_1: + description: | + If set, specifies the override behavior for the + browser. For example, this header might specify that the browser + use a download program to save this file rather than show the + file, which is the default. If not set, this header is not + returned by this operation. + in: header + required: false + type: string +Content-Encoding: + description: | + If set, the value of the ``Content-Encoding`` + metadata. + in: header + required: false + type: string +Content-Encoding_1: + description: | + If set, the value of the ``Content-Encoding`` + metadata. If not set, the operation does not return this header. + in: header + required: false + type: string +Content-Length: + description: | + If the operation succeeds, this value is zero + (0). If the operation fails, this value is the length of the error + text in the response body. + in: header + required: true + type: string +Content-Length_1: + description: | + Set to the length of the object content. Do not + set if chunked transfer encoding is being used. + in: header + required: false + type: integer +Content-Length_2: + description: | + 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. + in: header + required: true + type: string +Content-Length_3: + description: | + HEAD operations do not return content. The + ``Content-Length`` header value is not the size of the response + body but is the size of the object, in bytes. + in: header + required: true + type: string +Content-Length_4: + description: | + The length of the object content in the response + body, in bytes. + in: header + required: true + type: string +Content-Type: + description: | + Changes the MIME type for the object. + in: header + required: false + type: string +Content-Type_1: + description: | + If the operation fails, this value is the MIME + type of the error text in the response body. + in: header + required: true + type: string +Content-Type_2: + description: | + The MIME type of the object. + in: header + required: true + type: string +Content-Type_3: + description: | + 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. + in: header + required: true + type: string +Date: + description: | + 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. + in: header + required: true + type: string +Destination: + description: | + The container and object name of the destination + object in the form of ``/container/object``. You must UTF-8-encode + and then URL-encode the names of the destination container and + object before you include them in this header. + in: header + required: true + type: string +ETag: + description: | + The MD5 checksum of the copied object content. + The value is not quoted. + in: header + required: true + type: string +ETag_1: + description: | + The MD5 checksum value of the request body. For + example, the MD5 checksum value of the object content. You are + strongly recommended to compute the MD5 checksum value of object + content and include it in the request. This enables the Object + Storage API to check the integrity of the upload. The value is not + quoted. + in: header + required: false + type: string +ETag_2: + description: | + For objects smaller than 5 GB, this value is the + MD5 checksum of the object content. The value is not quoted. For + manifest objects, this value is the MD5 checksum of the + concatenated string of MD5 checksums and ETags for each of the + segments in the manifest, and not the MD5 checksum of the content + that was downloaded. Also the value is enclosed in double-quote + characters. You are strongly recommended to compute the MD5 + checksum of the response body as it is received and compare this + value with the one in the ETag header. If they differ, the content + was corrupted, so retry the operation. + in: header + required: true + type: string +If-Match: + description: | + See `Request for Comments: 2616 + `_. + in: header + required: false + type: string +If-Modified-Since: + description: | + See `Request for Comments: 2616 + `_. + in: header + required: false + type: string +If-None-Match: + description: | + In combination with ``Expect: 100-Continue``, + specify an ``"If- None-Match: *"`` header to query whether the + server already has a copy of the object before any data is sent. + in: header + required: false + type: string +If-Unmodified-Since: + description: | + See `Request for Comments: 2616 + `_. + in: header + required: false + type: string +Last-Modified: + description: | + The date and time when the object was created or its metadata was + changed. + + 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``. + in: header + required: true + type: string +Range: + description: | + The ranges of content to get. You can use the + ``Range`` header to get portions of data by using one or more + range specifications. To specify many ranges, separate the range + specifications with a comma. The types of range specifications + are: - **Byte range specification**. Use FIRST_BYTE_OFFSET to + specify the start of the data range, and LAST_BYTE_OFFSET to + specify the end. You can omit the LAST_BYTE_OFFSET and if you + do, the value defaults to the offset of the last byte of data. + - **Suffix byte range specification**. Use LENGTH bytes to specify + the length of the data range. The following forms of the header + specify the following ranges of data: - ``Range: bytes=-5``. The + last five bytes. - ``Range: bytes=10-15``. The five bytes of data + after a 10-byte offset. - ``Range: bytes=10-15,-5``. A multi- + part response that contains the last five bytes and the five + bytes of data after a 10-byte offset. The ``Content-Type`` + response header contains ``multipart/byteranges``. - ``Range: + bytes=4-6``. Bytes 4 to 6 inclusive. - ``Range: bytes=2-2``. Byte + 2, the third byte of the data. - ``Range: bytes=6-``. Byte 6 and + after. - ``Range: bytes=1-3,2-5``. A multi-part response that + contains bytes 1 to 3 inclusive, and bytes 2 to 5 inclusive. The + ``Content-Type`` response header contains + ``multipart/byteranges``. + in: header + required: false + type: string +Transfer-Encoding: + description: | + Set to ``chunked`` to enable chunked transfer + encoding. If used, do not set the ``Content-Length`` header to a + non-zero value. + in: header + required: false + type: string +X-Account-Bytes-Used: + description: | + The total number of bytes that are stored in + Object Storage for the account. + in: header + required: true + type: integer +X-Account-Container-Count: + description: | + The number of containers. + in: header + required: true + type: integer +X-Account-Meta-name: + description: | + 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}``). + in: header + required: false + type: string +X-Account-Meta-name_1: + description: | + The account metadata. The ``{name}`` is the name + of metadata item that you want to add, update, or delete. To + delete this item, send an empty value in this header. You must + specify an ``X-Account-Meta- {name}`` header for each metadata + item (for each ``{name}``) that you want to add, update, or + delete. + in: header + required: false + type: string +X-Account-Meta-Temp-URL-Key: + description: | + The secret key value for temporary URLs. If not + set, this header is not returned in the response. + in: header + required: false + type: string +X-Account-Meta-Temp-URL-Key-2: + description: | + A second secret key value for temporary URLs. If + not set, this header is not returned in the response. + The second key enables you to rotate keys by having + two active keys at the same time. + in: header + required: false + type: string +X-Account-Object-Count: + description: | + The number of objects in the account. + in: header + required: true + type: integer +X-Auth-Token: + description: | + Authentication token. If you omit this header, + your request fails unless the account owner has granted you access + through an access control list (ACL). + in: header + required: false + type: string +X-Auth-Token_1: + description: | + Authentication token. + in: header + required: true + type: string +X-Container-Bytes-Used: + description: | + The total number of bytes used. + in: header + required: true + type: integer +X-Container-Meta-Access-Control-Allow-Origin: + description: | + Originating URLs allowed to make cross-origin + requests (CORS), separated by spaces. This heading applies to the + container only, and all objects within the container with this + header applied are CORS-enabled for the allowed origin URLs. A + browser (user-agent) typically issues a `preflighted request + `_ , which is an OPTIONS call + that verifies the origin is allowed to make the request. The + Object Storage service returns 200 if the originating URL is + listed in this header parameter, and issues a 401 if the + originating URL is not allowed to make a cross-origin request. + Once a 200 is returned, the browser makes a second request to the + Object Storage service to retrieve the CORS-enabled object. + in: header + required: false + type: string +X-Container-Meta-Access-Control-Expose-Headers: + description: | + Headers the Object Storage service exposes to the + browser (technically, through the ``user-agent`` setting), in the + request response, separated by spaces. By default the Object + Storage service returns the following values for this header: - + All “simple response headers” as listed on + `http://www.w3.org/TR/cors/#simple-response-header + `_. - The + headers ``etag``, ``x-timestamp``, ``x-trans-id``. - All metadata + headers (``X-Container-Meta-*`` for containers and ``X-Object- + Meta-*`` for objects) headers listed in ``X-Container- Meta- + Access-Control-Expose-Headers``. + in: header + required: false + type: string +X-Container-Meta-Access-Control-Max-Age: + description: | + Maximum time for the origin to hold the preflight + results. A browser may make an OPTIONS call to verify the origin + is allowed to make the request. Set the value to an integer number + of seconds after the time that the request was received. + in: header + required: false + type: string +X-Container-Meta-name: + description: | + The container metadata, where ``{name}`` is the + name of metadata item. You must specify an ``X-Container-Meta- + {name}`` header for each metadata item (for each ``{name}``) that + you want to add or update. + in: header + required: false + type: string +X-Container-Meta-name_1: + description: | + The custom container metadata item, where + ``{name}`` is the name of the metadata item. One ``X-Container- + Meta- {name}`` response header appears for each metadata item (for + each ``{name}``). + in: header + required: true + type: string +X-Container-Meta-Quota-Bytes: + description: | + Sets maximum size of the container, in bytes. + Typically these values are set by an administrator. Returns a 413 + response (request entity too large) when an object PUT operation + exceeds this quota value. + in: header + required: false + type: string +X-Container-Meta-Quota-Count: + description: | + Sets maximum object count of the container. + Typically these values are set by an administrator. Returns a 413 + response (request entity too large) when an object PUT operation + exceeds this quota value. + in: header + required: false + type: string +X-Container-Meta-Temp-URL-Key: + description: | + The secret key value for temporary URLs. + in: header + required: false + type: string +X-Container-Meta-Temp-URL-Key-2: + description: | + A second secret key value for temporary URLs. The + second key enables you to rotate keys by having two active keys at + the same time. + in: header + required: false + type: string +X-Container-Meta-Web-Directory-Type: + description: | + Sets the content-type of directory marker + objects. If the header is not set, default is + ``application/directory``. Directory marker objects are 0-byte + objects that represent directories to create a simulated + hierarchical structure. For example, if you set ``"X-Container- + Meta-Web-Directory- Type: text/directory"``, Object Storage treats + 0-byte objects with a content-type of ``text/directory`` as + directories rather than objects. + in: header + required: false + type: string +X-Container-Object-Count: + description: | + The number of objects. + in: header + required: true + type: integer +X-Container-Read: + description: | + Sets a container access control list (ACL) that grants read access. + Container ACLs are available on any Object Storage cluster, and are + enabled by container rather than by cluster. + + To set the container read ACL: + + .. code-block:: bash + + $ curl -X {PUT|POST} -i -H "X-Auth-Token: TOKEN" -H \ + "X-Container-Read: ACL" STORAGE_URL/CONTAINER + + For example: + + .. code-block:: bash + + $ curl -X PUT -i \ + -H "X-Auth-Token: 0101010101" \ + -H "X-Container-Read: .r:*" \ + http://swift.example.com/v1/AUTH_bob/read_container + + In the command, specify the ACL in the ``X-Container-Read`` header, + as follows: + + - ``.r:*`` All referrers. + + - ``.r:example.com,swift.example.com`` Comma-separated list of + referrers. + + - ``.rlistings`` Container listing access. + + - ``AUTH_username`` Access to a user who authenticates through a + legacy or non-OpenStack-Identity-based authentication system. + + - ``LDAP_`` Access to all users who authenticate through an LDAP- + based legacy or non-OpenStack-Identity-based authentication + system. + in: header + required: false + type: string +X-Container-Read_1: + description: | + The ACL that grants read access. If not set, this + header is not returned by this operation. + in: header + required: false + type: string +X-Container-Sync-Key: + description: | + Sets the secret key for container + synchronization. If you remove the secret key, synchronization is + halted. + in: header + required: false + type: string +X-Container-Sync-Key_1: + description: | + The secret key for container synchronization. If + not set, this header is not returned by this operation. + in: header + required: false + type: string +X-Container-Sync-To: + description: | + Sets the destination for container + synchronization. Used with the secret key indicated in the ``X + -Container-Sync-Key`` header. If you want to stop a container from + synchronizing, send a blank value for the ``X-Container-Sync-Key`` + header. + in: header + required: false + type: string +X-Container-Sync-To_1: + description: | + The destination for container synchronization. If + not set, this header is not returned by this operation. + in: header + required: false + type: string +X-Container-Write: + description: | + Sets an ACL that grants write access. + in: header + required: false + type: string +X-Container-Write_1: + description: | + The ACL that grants write access. If not set, + this header is not returned by this operation. + in: header + required: false + type: string +X-Copied-From: + description: | + For a copied object, shows the container and + object name from which the new object was copied. The value is in + the ``{container}/{object}`` format. + in: header + required: false + type: string +X-Copied-From-Last-Modified: + description: | + For a copied object, the date and time in `UNIX + Epoch time stamp format + `_ when the container and + object name from which the new object was copied was last + modified. For example, ``1440619048`` is equivalent to ``Mon, + Wed, 26 Aug 2015 19:57:28 GMT``. + in: header + required: false + type: integer +X-Copy-From: + description: | + If set, this is the name of an object used to + create the new object by copying the ``X-Copy-From`` object. The + value is in form ``{container}/{object}``. You must UTF-8-encode + and then URL-encode the names of the container and object before + you include them in the header. Using PUT with ``X-Copy-From`` + has the same effect as using the COPY operation to copy an object. + Using ``Range`` header with ``X-Copy-From`` will create a new + partial copied object with bytes set by ``Range``. + in: header + required: false + type: string +X-Delete-After: + description: | + The number of seconds after which the system + removes the object. Internally, the Object Storage system stores + this value in the ``X -Delete-At`` metadata item. + in: header + required: false + type: integer +X-Delete-At: + description: | + The date and time in `UNIX Epoch time stamp + format `_ when the system + removes the object. For example, ``1440619048`` is equivalent to + ``Mon, Wed, 26 Aug 2015 19:57:28 GMT``. + in: header + required: false + type: integer +X-Delete-At_1: + description: | + If set, the date and time in `UNIX Epoch time + stamp format `_ when the + system deletes the object. For example, ``1440619048`` is + equivalent to ``Mon, Wed, 26 Aug 2015 19:57:28 GMT``. If not set, + this operation does not return this header. + in: header + required: false + type: integer +X-Detect-Content-Type: + description: | + If set to ``true``, Object Storage guesses the + content type based on the file extension and ignores the value + sent in the ``Content- Type`` header, if present. + in: header + required: false + type: boolean +X-Fresh-Metadata: + description: | + Enables object creation that omits existing user + metadata. If set to ``true``, the COPY request creates an object + without existing user metadata. Default value is ``false``. + in: header + required: false + type: boolean +X-Newest: + description: | + 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. + in: header + required: false + type: boolean +X-Object-Manifest: + description: | + Set to specify that this is a dynamic large + object manifest object. The value is the container and object name + prefix of the segment objects in the form ``container/prefix``. + You must UTF-8-encode and then URL-encode the names of the + container and prefix before you include them in this header. + in: header + required: false + type: string +X-Object-Manifest_1: + description: | + If set, to this is a dynamic large object + manifest object. The value is the container and object name prefix + of the segment objects in the form ``container/prefix``. + in: header + required: false + type: string +X-Object-Meta-name: + description: | + The object metadata, where ``{name}`` is the name + of the metadata item. You must specify an ``X-Object-Meta- + {name}`` header for each metadata ``{name}`` item that you want to + add or update. + in: header + required: false + type: string +X-Object-Meta-name_1: + description: | + The custom object metadata item, where ``{name}`` + is the name of the metadata item. One ``X-Object-Meta- {name}`` + response header appears for each metadata ``{name}`` item. + in: header + required: true + type: string +X-Remove-Container-name: + description: | + Removes the metadata item named ``{name}``. For + example, ``X -Remove-Container-Read`` removes the ``X-Container- + Read`` metadata item. + in: header + required: false + type: string +X-Remove-Versions-Location: + description: | + Set to any value to disable versioning. + in: header + required: false + type: string +X-Static-Large-Object: + description: | + Set to ``true`` if this object is a static large + object manifest object. + in: header + required: true + type: boolean +X-Timestamp: + description: | + 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``. + in: header + required: true + type: integer +X-Trans-Id: + description: | + A unique transaction ID for this request. Your + service provider might need this value if you report a problem. + in: header + required: true + type: string +X-Trans-Id-Extra: + description: | + Extra transaction information. Use the ``X-Trans- + Id-Extra`` request header to include extra information to help you + debug any errors that might occur with large object upload and + other Object Storage transactions. Object Storage appends the + first 32 characters of the ``X-Trans-Id- Extra`` request header + value to the transaction ID value in the generated ``X-Trans-Id`` + response header. You must UTF-8-encode and then URL-encode the + extra transaction information before you include it in the ``X + -Trans-Id-Extra`` request header. For example, you can include + extra transaction information when you upload `large objects + `_ such as images. When + you upload each segment and the manifest, include the same value + in the ``X-Trans-Id-Extra`` request header. If an error occurs, + you can find all requests that are related to the large object + upload in the Object Storage logs. You can also use ``X-Trans-Id- + Extra`` strings to help operators debug requests that fail to + receive responses. The operator can search for the extra + information in the logs. + in: header + required: false + type: string +X-Versions-Location: + description: | + Enables versioning on this container. The value + is the name of another container. You must UTF-8-encode and then + URL-encode the name before you include it in the header. To + disable versioning, set the header to an empty string. + in: header + required: false + type: string +X-Versions-Location_1: + description: | + Enables versioning on this container. The value + is the name of another container. You must UTF-8-encode and then + URL-encode the name before you include it in the header. To + disable versioning, set the header to an empty string. + in: header + required: true + type: string + +# variables in path +account: + description: | + The unique name for the account. An account is + also known as the project or tenant. + in: path + required: false + type: string +container: + description: | + The unique name for the container. The container + name must be from 1 to 256 characters long and can start with any + character and contain any pattern. Character set must be UTF-8. + The container name cannot contain a slash (``/``) character + because this character delimits the container and object name. For + example, ``/account/container/object``. + in: path + required: false + type: string +object: + description: | + The unique name for the object. + in: path + required: false + type: string + +# variables in query +delimiter: + description: | + Delimiter value, which returns the object names + that are nested in the container. If you do not set a prefix and + set the delimiter to "/" you may get unexpected results where all + the objects are returned instead of only those with the delimiter + set. + in: query + required: false + type: string +end_marker: + description: | + For a string value, x , returns container names + that are less than the marker value. + in: query + required: false + type: string +filename: + description: | + Overrides the default file name. Object Storage + generates a default file name for GET temporary URLs that is based + on the object name. Object Storage returns this value in the + ``Content-Disposition`` response header. Browsers can interpret + this file name value as a file attachment to save. For more + information about temporary URLs, see `Temporary URL middleware + `_. + in: query + required: false + type: string +format: + description: | + 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. + in: query + required: false + type: string +limit: + description: | + For an integer value n , limits the number of + results to n . + in: query + required: false + type: integer +marker: + description: | + For a string value, x , returns container names + that are greater than the marker value. + in: query + required: false + type: string +multipart-manifest: + description: | + If ``?multipart-manifest=put``, the object is a + static large object manifest and the body contains the manifest. + in: query + required: false + type: string +multipart-manifest_1: + description: | + If you include the ``multipart-manifest=delete`` + query parameter and the object is a static large object, the + segment objects and manifest object are deleted. If you omit the + ``multipart- manifest=delete`` query parameter and the object is a + static large object, the manifest object is deleted but the + segment objects are not deleted. For a bulk delete, the response + body looks the same as it does for a normal bulk delete. In + contrast, a plain object DELETE response has an empty body. + in: query + required: false + type: string +multipart-manifest_2: + description: | + If you include the ``multipart-manifest=get`` + query parameter and the object is a large object, the object + contents are not returned. Instead, the manifest is returned in + the ``X-Object-Manifest`` response header for dynamic large + objects or in the response body for static large objects. + in: query + required: false + type: string +path: + description: | + For a string value, returns the object names that + are nested in the pseudo path. + in: query + required: false + type: string +prefix: + description: | + Prefix value. Named items in the response begin + with this value. + in: query + required: false + type: string +swiftinfo_expires: + description: | + Filters the response by the expiration date and + time in `UNIX Epoch time stamp format + `_. For example, + ``1440619048`` is equivalent to ``Mon, Wed, 26 Aug 2015 19:57:28 + GMT``. + in: query + required: false + type: integer +swiftinfo_sig: + description: | + A hash-based message authentication code (HMAC) + that enables access to administrator-only information. To use this + parameter, the ``swiftinfo_expires`` parameter is also required. + in: query + required: false + type: string +temp_url_expires: + description: | + The date and time in `UNIX Epoch time stamp + format `_ when the + signature for temporary URLs expires. For example, ``1440619048`` + is equivalent to ``Mon, Wed, 26 Aug 2015 19:57:28 GMT``. For more + information about temporary URLs, see `Temporary URL middleware + `_. + in: query + required: true + type: integer +temp_url_sig: + description: | + Used with temporary URLs to sign the request with + an HMAC-SHA1 cryptographic signature that defines the allowed HTTP + method, expiration date, full path to the object, and the secret + key for the temporary URL. For more information about temporary + URLs, see `Temporary URL middleware + `_. + in: query + required: true + type: string + +# variables in body +bytes: + description: | + The total number of bytes that are stored in + Object Storage for the account. + in: body + required: true + type: integer +content_type: + description: | + The content type of the object. + in: body + required: true + type: string +count: + description: | + The number of objects in the container. + in: body + required: true + type: integer +hash: + description: | + The MD5 checksum value of the object content. + in: body + required: true + type: string +last_modified: + description: | + The date and time when the object was last modified. + + 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``. + in: body + required: true + type: string +name: + description: | + The name of the container. + in: body + required: true + type: string + + diff --git a/api-ref/source/samples/account-containers-list-http-request-json.txt b/api-ref/source/samples/account-containers-list-http-request-json.txt new file mode 100644 index 0000000000..a4b315556d --- /dev/null +++ b/api-ref/source/samples/account-containers-list-http-request-json.txt @@ -0,0 +1 @@ +curl -i https://23.253.72.207/v1/$account?format=json -X GET -H "X-Auth-Token: $token" \ No newline at end of file diff --git a/api-ref/source/samples/account-containers-list-http-request-xml.txt b/api-ref/source/samples/account-containers-list-http-request-xml.txt new file mode 100644 index 0000000000..cf255617f2 --- /dev/null +++ b/api-ref/source/samples/account-containers-list-http-request-xml.txt @@ -0,0 +1,2 @@ +curl -i https://23.253.72.207/v1/$account?format=xml \ + -X GET -H "X-Auth-Token: $token" \ No newline at end of file diff --git a/api-ref/source/samples/account-containers-list-http-response-json.txt b/api-ref/source/samples/account-containers-list-http-response-json.txt new file mode 100644 index 0000000000..0cdba62a8a --- /dev/null +++ b/api-ref/source/samples/account-containers-list-http-response-json.txt @@ -0,0 +1,11 @@ +HTTP/1.1 200 OK +Content-Length: 96 +X-Account-Object-Count: 1 +X-Timestamp: 1389453423.35964 +X-Account-Meta-Subject: Literature +X-Account-Bytes-Used: 14 +X-Account-Container-Count: 2 +Content-Type: application/json; charset=utf-8 +Accept-Ranges: bytes +X-Trans-Id: tx274a77a8975c4a66aeb24-0052d95365 +Date: Fri, 17 Jan 2014 15:59:33 GMT \ No newline at end of file diff --git a/api-ref/source/samples/account-containers-list-http-response-xml.txt b/api-ref/source/samples/account-containers-list-http-response-xml.txt new file mode 100644 index 0000000000..6ad781aaec --- /dev/null +++ b/api-ref/source/samples/account-containers-list-http-response-xml.txt @@ -0,0 +1,11 @@ +HTTP/1.1 200 OK +Content-Length: 262 +X-Account-Object-Count: 1 +X-Timestamp: 1389453423.35964 +X-Account-Meta-Subject: Literature +X-Account-Bytes-Used: 14 +X-Account-Container-Count: 2 +Content-Type: application/xml; charset=utf-8 +Accept-Ranges: bytes +X-Trans-Id: tx69f60bc9f7634a01988e6-0052d9544b +Date: Fri, 17 Jan 2014 16:03:23 GMT \ No newline at end of file diff --git a/api-ref/source/samples/account-containers-list-response.json b/api-ref/source/samples/account-containers-list-response.json new file mode 100644 index 0000000000..4ae34aa4ca --- /dev/null +++ b/api-ref/source/samples/account-containers-list-response.json @@ -0,0 +1,12 @@ +[ + { + "count": 0, + "bytes": 0, + "name": "janeausten" + }, + { + "count": 1, + "bytes": 14, + "name": "marktwain" + } +] diff --git a/api-ref/source/samples/account-containers-list-response.xml b/api-ref/source/samples/account-containers-list-response.xml new file mode 100644 index 0000000000..d8f51cfa0d --- /dev/null +++ b/api-ref/source/samples/account-containers-list-response.xml @@ -0,0 +1,13 @@ + + + + janeausten + 0 + 0 + + + marktwain + 1 + 14 + + diff --git a/api-ref/source/samples/capabilities-list-response.json b/api-ref/source/samples/capabilities-list-response.json new file mode 100644 index 0000000000..bcc91f7d53 --- /dev/null +++ b/api-ref/source/samples/capabilities-list-response.json @@ -0,0 +1,7 @@ +{ + "swift": { + "version": "1.11.0" + }, + "staticweb": {}, + "tempurl": {} +} diff --git a/api-ref/source/samples/containers-list-http-request.txt b/api-ref/source/samples/containers-list-http-request.txt new file mode 100644 index 0000000000..4101ce80e5 --- /dev/null +++ b/api-ref/source/samples/containers-list-http-request.txt @@ -0,0 +1,3 @@ +GET /{api_version}/{account} HTTP/1.1 +Host: storage.swiftdrive.com +X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb \ No newline at end of file diff --git a/api-ref/source/samples/containers-list-http-response.txt b/api-ref/source/samples/containers-list-http-response.txt new file mode 100644 index 0000000000..43070e5235 --- /dev/null +++ b/api-ref/source/samples/containers-list-http-response.txt @@ -0,0 +1,9 @@ +HTTP/1.1 200 Ok +Date: Thu, 07 Jun 2010 18:57:07 GMT +Content-Type: text/plain; charset=UTF-8 +Content-Length: 32 + +images +movies +documents +backups \ No newline at end of file diff --git a/api-ref/source/samples/endpoints-list-response-headers.json b/api-ref/source/samples/endpoints-list-response-headers.json new file mode 100644 index 0000000000..a6de5f0681 --- /dev/null +++ b/api-ref/source/samples/endpoints-list-response-headers.json @@ -0,0 +1,14 @@ +{ + "endpoints": [ + "http://storage01.swiftdrive.com:6008/d8/583/AUTH_dev/EC_cont1/obj", + "http://storage02.swiftdrive.com:6008/d2/583/AUTH_dev/EC_cont1/obj", + "http://storage02.swiftdrive.com:6006/d3/583/AUTH_dev/EC_cont1/obj", + "http://storage02.swiftdrive.com:6008/d5/583/AUTH_dev/EC_cont1/obj", + "http://storage01.swiftdrive.com:6007/d7/583/AUTH_dev/EC_cont1/obj", + "http://storage02.swiftdrive.com:6007/d4/583/AUTH_dev/EC_cont1/obj", + "http://storage01.swiftdrive.com:6006/d6/583/AUTH_dev/EC_cont1/obj" + ], + "headers": { + "X-Backend-Storage-Policy-Index": "2" + } +} diff --git a/api-ref/source/samples/endpoints-list-response.json b/api-ref/source/samples/endpoints-list-response.json new file mode 100644 index 0000000000..eeba7c1738 --- /dev/null +++ b/api-ref/source/samples/endpoints-list-response.json @@ -0,0 +1,8 @@ +{ + "endpoints": [ + "http://storage02.swiftdrive:6002/d2/617/AUTH_dev", + "http://storage01.swiftdrive:6002/d8/617/AUTH_dev", + "http://storage01.swiftdrive:6002/d11/617/AUTH_dev" + ], + "headers": {} +} diff --git a/api-ref/source/samples/goodbyeworld.txt b/api-ref/source/samples/goodbyeworld.txt new file mode 100644 index 0000000000..aebc9c0c05 --- /dev/null +++ b/api-ref/source/samples/goodbyeworld.txt @@ -0,0 +1 @@ +Goodbye World! \ No newline at end of file diff --git a/api-ref/source/samples/helloworld.txt b/api-ref/source/samples/helloworld.txt new file mode 100644 index 0000000000..6900abf34d --- /dev/null +++ b/api-ref/source/samples/helloworld.txt @@ -0,0 +1 @@ +Hello World Again! \ No newline at end of file diff --git a/api-ref/source/samples/objects-list-http-response-json.txt b/api-ref/source/samples/objects-list-http-response-json.txt new file mode 100644 index 0000000000..2efe63a3f2 --- /dev/null +++ b/api-ref/source/samples/objects-list-http-response-json.txt @@ -0,0 +1,10 @@ +HTTP/1.1 200 OK +Content-Length: 341 +X-Container-Object-Count: 2 +Accept-Ranges: bytes +X-Container-Meta-Book: TomSawyer +X-Timestamp: 1389727543.65372 +X-Container-Bytes-Used: 26 +Content-Type: application/json; charset=utf-8 +X-Trans-Id: tx26377fe5fab74869825d1-0052d6bdff +Date: Wed, 15 Jan 2014 16:57:35 GMT \ No newline at end of file diff --git a/api-ref/source/samples/objects-list-http-response-xml.txt b/api-ref/source/samples/objects-list-http-response-xml.txt new file mode 100644 index 0000000000..eb17bb2a6a --- /dev/null +++ b/api-ref/source/samples/objects-list-http-response-xml.txt @@ -0,0 +1,10 @@ +HTTP/1.1 200 OK +Content-Length: 500 +X-Container-Object-Count: 2 +Accept-Ranges: bytes +X-Container-Meta-Book: TomSawyer +X-Timestamp: 1389727543.65372 +X-Container-Bytes-Used: 26 +Content-Type: application/xml; charset=utf-8 +X-Trans-Id: txc75ea9a6e66f47d79e0c5-0052d6be76 +Date: Wed, 15 Jan 2014 16:59:35 GMT \ No newline at end of file diff --git a/api-ref/source/samples/objects-list-response.json b/api-ref/source/samples/objects-list-response.json new file mode 100644 index 0000000000..b104d3a9a6 --- /dev/null +++ b/api-ref/source/samples/objects-list-response.json @@ -0,0 +1,16 @@ +[ + { + "hash": "451e372e48e0f6b1114fa0724aa79fa1", + "last_modified": "2014-01-15T16:41:49.390270", + "bytes": 14, + "name": "goodbye", + "content_type": "application/octet-stream" + }, + { + "hash": "ed076287532e86365e841e92bfc50d8c", + "last_modified": "2014-01-15T16:37:43.427570", + "bytes": 12, + "name": "helloworld", + "content_type": "application/octet-stream" + } +] diff --git a/api-ref/source/samples/objects-list-response.xml b/api-ref/source/samples/objects-list-response.xml new file mode 100644 index 0000000000..07fda614c1 --- /dev/null +++ b/api-ref/source/samples/objects-list-response.xml @@ -0,0 +1,17 @@ + + + + goodbye + 451e372e48e0f6b1114fa0724aa79fa1 + 14 + application/octet-stream + 2014-01-15T16:41:49.390270 + + + helloworld + ed076287532e86365e841e92bfc50d8c + 12 + application/octet-stream + 2014-01-15T16:37:43.427570 + + diff --git a/api-ref/source/storage-account-services.inc b/api-ref/source/storage-account-services.inc new file mode 100644 index 0000000000..17f228c543 --- /dev/null +++ b/api-ref/source/storage-account-services.inc @@ -0,0 +1,380 @@ +.. -*- rst -*- + +======== +Accounts +======== + +Lists containers for an account. Creates, updates, shows, and +deletes account metadata. + +Account metadata operations work differently than container and +object metadata operations work. Depending on the contents of your +POST account metadata request, the Object Storage API updates the +metadata in one of these ways: + +**Account metadata operations** + ++----------------------------------------------------------+---------------------------------------------------------------+ +| POST request body contains | Description | ++----------------------------------------------------------+---------------------------------------------------------------+ +| A metadata key without a value. | The API removes the metadata item from the account. | +| | | +| The metadata key already exists for the account. | | ++----------------------------------------------------------+---------------------------------------------------------------+ +| A metadata key without a value. | The API ignores the metadata key. | +| | | +| The metadata key does not already exist for the account. | | ++----------------------------------------------------------+---------------------------------------------------------------+ +| A metadata key value. | The API updates the metadata key value for the account. | +| | | +| The metadata key already exists for the account. | | ++----------------------------------------------------------+---------------------------------------------------------------+ +| A metadata key value. | The API adds the metadata key and value pair, or item, to the | +| | account. | +| The metadata key does not already exist for the account. | | ++----------------------------------------------------------+---------------------------------------------------------------+ +| One or more account metadata items are omitted. | The API does not change the existing metadata items. | +| | | +| The metadata items already exist for the account. | | ++----------------------------------------------------------+---------------------------------------------------------------+ + + + +For these requests, specifying the ``X-Remove-Account-Meta-*`` +request header for the key with any value is equivalent to +specifying the ``X-Account-Meta-*`` request header with an empty +value. + +Metadata keys must be treated as case-insensitive at all times. +These keys can contain ASCII 7-bit characters that are not control +(0-31) characters, DEL, or a separator character, according to +`HTTP/1.1 `_ . +Also, Object Storage does not support the underscore character, +which it silently converts to a hyphen. + +The metadata values in Object Storage do not follow HTTP/1.1 rules +for character encodings. You must use a UTF-8 encoding to get a +byte array for any string that contains characters that are not in +the 7-bit ASCII 0-127 range. Otherwise, Object Storage returns the +404 response code for ISO-8859-1 characters in the 128-255 range, +which is a direct violation of the HTTP/1.1 `basic rules +`_. + + +Show account details and list containers +======================================== + +.. rest_method:: GET /v1/{account} + +Shows details for an account and lists containers, sorted by name, in the account. + +The sort order for the name is based on a binary comparison, a +single built-in collating sequence that compares string data by +using the SQLite memcmp() function, regardless of text encoding. +See `Collating Sequences +`_. + +Example requests and responses: + +- Show account details and list containers and ask for a JSON + response: + + :: + + curl -i $publicURL?format=json -X GET -H "X-Auth-Token: $token" + + +- List containers and ask for an XML response: + + :: + + curl -i $publicURL?format=xml -X GET -H "X-Auth-Token: $token" + + +The response body returns a list of containers. The default +response (``text/plain``) returns one container per line. + +If you use query parameters to page through a long list of +containers, you have reached the end of the list if the number of +items in the returned list is less than the request ``limit`` +value. The list contains more items if the number of items in the +returned list equals the ``limit`` value. + +When asking for a list of containers and there are none, the +response behavior changes depending on whether the request format +is text, JSON, or XML. For a text response, you get a 204 , because +there is no content. However, for a JSON or XML response, you get a +200 with content indicating an empty array. + +If the request succeeds, the operation returns one of these status +codes: + +- ``OK (200)``. Success. The response body lists the containers. + +- ``No Content (204)``. 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. + + +Normal response codes: 200 +Error response codes:204, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - account: account + - limit: limit + - marker: marker + - end_marker: end_marker + - format: format + - prefix: prefix + - delimiter: delimiter + - X-Auth-Token: X-Auth-Token + - X-Newest: X-Newest + - Accept: Accept + - X-Trans-Id-Extra: X-Trans-Id-Extra + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - Content-Length: Content-Length + - X-Account-Meta-name: X-Account-Meta-name + - X-Account-Object-Count: X-Account-Object-Count + - X-Account-Meta-Temp-URL-Key-2: X-Account-Meta-Temp-URL-Key-2 + - X-Timestamp: X-Timestamp + - X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key + - X-Trans-Id: X-Trans-Id + - Date: Date + - X-Account-Bytes-Used: X-Account-Bytes-Used + - X-Account-Container-Count: X-Account-Container-Count + - Content-Type: Content-Type + - count: count + - bytes: bytes + - name: name + + + +Response Example +---------------- + +.. literalinclude:: samples/account-containers-list-http-response-xml.txt + :language: javascript + + + + + +Create, update, or delete account metadata +========================================== + +.. rest_method:: POST /v1/{account} + +Creates, updates, or deletes account metadata. + +To create, update, or delete metadata, use the ``X-Account- +Meta-{name}`` request header, where ``{name}`` is the name of the +metadata item. + +Subsequent requests for the same key and value pair overwrite the +existing value. + +To delete a metadata header, send an empty value for that header, +such as for the ``X-Account-Meta-Book`` header. If the tool you use +to communicate with Object Storage, such as an older version of +cURL, does not support empty headers, send the ``X-Remove-Account- +Meta-{name}`` header with an arbitrary value. For example, ``X +-Remove-Account-Meta-Book: x``. The operation ignores the arbitrary +value. + +If the container already has other custom metadata items, a request +to create, update, or delete metadata does not affect those items. + +This operation does not accept a request body. + +Example requests and responses: + +- Create account metadata: + + :: + + curl -i $publicURL -X POST -H "X-Auth-Token: $token" -H "X-Account-Meta-Book: MobyDick" -H "X-Account-Meta-Subject: Literature" + + + + + :: + + HTTP/1.1 204 No Content + Content-Length: 0 + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: tx8c2dd6aee35442a4a5646-0052d954fb + Date: Fri, 17 Jan 2014 16:06:19 GMT + + +- Update account metadata: + + :: + + curl -i $publicURL -X POST -H "X-Auth-Token: $token" -H "X-Account-Meta-Subject: AmericanLiterature" + + + + + :: + + HTTP/1.1 204 No Content + Content-Length: 0 + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: tx1439b96137364ab581156-0052d95532 + Date: Fri, 17 Jan 2014 16:07:14 GMT + + +- Delete account metadata: + + :: + + curl -i $publicURL -X POST -H "X-Auth-Token: $token" -H "X-Remove-Account-Meta-Subject: x" + + + + + :: + + HTTP/1.1 204 No Content + Content-Length: 0 + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: tx411cf57701424da99948a-0052d9556f + Date: Fri, 17 Jan 2014 16:08:15 GMT + + +If the request succeeds, the operation returns the ``No Content +(204)`` response code. + +To confirm your changes, issue a show account metadata request. + +Error response codes:204, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - account: account + - X-Auth-Token: X-Auth-Token + - X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key + - X-Account-Meta-Temp-URL-Key-2: X-Account-Meta-Temp-URL-Key-2 + - X-Account-Meta-name: X-Account-Meta-name + - Content-Type: Content-Type + - X-Detect-Content-Type: X-Detect-Content-Type + - X-Trans-Id-Extra: X-Trans-Id-Extra + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - Date: Date + - X-Timestamp: X-Timestamp + - Content-Length: Content-Length + - Content-Type: Content-Type + - X-Trans-Id: X-Trans-Id + + + + + +Show account metadata +===================== + +.. rest_method:: HEAD /v1/{account} + +Shows metadata for an account. + +Metadata for the account includes: + +- Number of containers + +- Number of objects + +- Total number of bytes that are stored in Object Storage for the + account + +Because the storage system can store large amounts of data, take +care when you represent the total bytes response as an integer; +when possible, convert it to a 64-bit unsigned integer if your +platform supports that primitive type. + +Do not include metadata headers in this request. + +Show account metadata request: + +:: + + curl -i $publicURL -X HEAD -H "X-Auth-Token: $token" + + + + +:: + + HTTP/1.1 204 No Content + Content-Length: 0 + X-Account-Object-Count: 1 + X-Account-Meta-Book: MobyDick + X-Timestamp: 1389453423.35964 + X-Account-Bytes-Used: 14 + X-Account-Container-Count: 2 + Content-Type: text/plain; charset=utf-8 + Accept-Ranges: bytes + X-Trans-Id: txafb3504870144b8ca40f7-0052d955d4 + Date: Fri, 17 Jan 2014 16:09:56 GMT + + +If the account or authentication token is not valid, the operation +returns the ``Unauthorized (401)`` response code. + +Error response codes:204,401, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - account: account + - X-Auth-Token: X-Auth-Token + - X-Newest: X-Newest + - X-Trans-Id-Extra: X-Trans-Id-Extra + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - Content-Length: Content-Length + - X-Account-Meta-name: X-Account-Meta-name + - X-Account-Object-Count: X-Account-Object-Count + - X-Account-Meta-Temp-URL-Key-2: X-Account-Meta-Temp-URL-Key-2 + - X-Timestamp: X-Timestamp + - X-Account-Meta-Temp-URL-Key: X-Account-Meta-Temp-URL-Key + - X-Trans-Id: X-Trans-Id + - Date: Date + - X-Account-Bytes-Used: X-Account-Bytes-Used + - X-Account-Container-Count: X-Account-Container-Count + - Content-Type: Content-Type + + + + + diff --git a/api-ref/source/storage-container-services.inc b/api-ref/source/storage-container-services.inc new file mode 100644 index 0000000000..6b69ef9d00 --- /dev/null +++ b/api-ref/source/storage-container-services.inc @@ -0,0 +1,503 @@ +.. -*- rst -*- + +========== +Containers +========== + +Lists objects in a container. Creates, shows details for, and +deletes containers. Creates, updates, shows, and deletes container +metadata. + + +Show container details and list objects +======================================= + +.. rest_method:: GET /v1/{account}/{container} + +Shows details for a container and lists objects, sorted by name, in the container. + +Specify query parameters in the request to filter the list and +return a subset of object names. Omit query parameters to return +the complete list of object names that are stored in the container, +up to 10,000 names. The 10,000 maximum value is configurable. To +view the value for the cluster, issue a GET ``/info`` request. + +Example requests and responses: + +- ``OK (200)``. Success. The response body lists the objects. + +- ``No Content (204)``. Success. The response body shows no objects. + Either the container has no objects 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. + +If the container does not exist, the call returns the ``Not Found +(404)`` response code. + +The operation returns the ``Range Not Satisfiable (416)`` response +code for any ranged GET requests that specify more than: + +- Fifty ranges. + +- Three overlapping ranges. + +- Eight non-increasing ranges. + + +Normal response codes: 200 +Error response codes:416,404,204, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - account: account + - container: container + - limit: limit + - marker: marker + - end_marker: end_marker + - prefix: prefix + - format: format + - delimiter: delimiter + - path: path + - X-Auth-Token: X-Auth-Token + - X-Newest: X-Newest + - Accept: Accept + - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key + - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2 + - X-Trans-Id-Extra: X-Trans-Id-Extra + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - X-Container-Meta-name: X-Container-Meta-name + - Content-Length: Content-Length + - X-Container-Object-Count: X-Container-Object-Count + - Accept-Ranges: Accept-Ranges + - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key + - X-Container-Bytes-Used: X-Container-Bytes-Used + - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2 + - X-Timestamp: X-Timestamp + - X-Trans-Id: X-Trans-Id + - Date: Date + - Content-Type: Content-Type + - hash: hash + - last_modified: last_modified + - bytes: bytes + - name: name + - content_type: content_type + + + +Response Example +---------------- + +.. literalinclude:: samples/objects-list-http-response-xml.txt + :language: javascript + + + + + + + +Create container +================ + +.. rest_method:: PUT /v1/{account}/{container} + +Creates a container. + +You do not need to check whether a container already exists before +issuing a PUT operation because the operation is idempotent: It +creates a container or updates an existing container, as +appropriate. + +Example requests and responses: + +- Create a container with no metadata: + + :: + + curl -i $publicURL/steven -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" + + + + + :: + + HTTP/1.1 201 Created + Content-Length: 0 + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: tx7f6b7fa09bc2443a94df0-0052d58b56 + Date: Tue, 14 Jan 2014 19:09:10 GMT + + +- Create a container with metadata: + + :: + + curl -i $publicURL/marktwain -X PUT -H "X-Auth-Token: $token" -H "X-Container-Meta-Book: TomSawyer" + + + + + :: + + HTTP/1.1 201 Created + Content-Length: 0 + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: tx06021f10fc8642b2901e7-0052d58f37 + Date: Tue, 14 Jan 2014 19:25:43 GMT + +Error response codes:201,204, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - account: account + - container: container + - X-Auth-Token: X-Auth-Token + - X-Container-Read: X-Container-Read + - X-Container-Write: X-Container-Write + - X-Container-Sync-To: X-Container-Sync-To + - X-Container-Sync-Key: X-Container-Sync-Key + - X-Versions-Location: X-Versions-Location + - X-Container-Meta-name: X-Container-Meta-name + - X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin + - X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age + - X-Container-Meta-Access-Control-Expose-Headers: X-Container-Meta-Access-Control-Expose-Headers + - Content-Type: Content-Type + - X-Detect-Content-Type: X-Detect-Content-Type + - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key + - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2 + - X-Trans-Id-Extra: X-Trans-Id-Extra + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - Date: Date + - X-Timestamp: X-Timestamp + - Content-Length: Content-Length + - Content-Type: Content-Type + - X-Trans-Id: X-Trans-Id + + + + + + +Create, update, or delete container metadata +============================================ + +.. rest_method:: POST /v1/{account}/{container} + +Creates, updates, or deletes custom metadata for a container. + +To create, update, or delete a custom metadata item, use the ``X +-Container-Meta-{name}`` header, where ``{name}`` is the name of +the metadata item. + +Subsequent requests for the same key and value pair overwrite the +previous value. + +To delete container metadata, send an empty value for that header, +such as for the ``X-Container-Meta-Book`` header. If the tool you +use to communicate with Object Storage, such as an older version of +cURL, does not support empty headers, send the ``X-Remove- +Container-Meta-{name}`` header with an arbitrary value. For +example, ``X-Remove-Container-Meta-Book: x``. The operation ignores +the arbitrary value. + +If the container already has other custom metadata items, a request +to create, update, or delete metadata does not affect those items. + +Example requests and responses: + +- Create container metadata: + + :: + + curl -i $publicURL/marktwain -X POST -H "X-Auth-Token: $token" -H "X-Container-Meta-Author: MarkTwain" -H "X-Container-Meta-Web-Directory-Type: text/directory" -H "X-Container-Meta-Century: Nineteenth" + + + + + :: + + HTTP/1.1 204 No Content + Content-Length: 0 + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: tx05dbd434c651429193139-0052d82635 + Date: Thu, 16 Jan 2014 18:34:29 GMT + + +- Update container metadata: + + :: + + curl -i $publicURL/marktwain -X POST -H "X-Auth-Token: $token" -H "X-Container-Meta-Author: SamuelClemens" + + + + + :: + + HTTP/1.1 204 No Content + Content-Length: 0 + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: txe60c7314bf614bb39dfe4-0052d82653 + Date: Thu, 16 Jan 2014 18:34:59 GMT + + +- Delete container metadata: + + :: + + curl -i $publicURL/marktwain -X POST -H "X-Auth-Token: $token" -H "X-Remove-Container-Meta-Century: x" + + + + + :: + + HTTP/1.1 204 No Content + Content-Length: 0 + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: tx7997e18da2a34a9e84ceb-0052d826d0 + Date: Thu, 16 Jan 2014 18:37:04 GMT + + +If the request succeeds, the operation returns the ``No Content +(204)`` response code. + +To confirm your changes, issue a show container metadata request. + +Error response codes:204, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - account: account + - container: container + - X-Auth-Token: X-Auth-Token + - X-Container-Read: X-Container-Read + - X-Remove-Container-name: X-Remove-Container-name + - X-Container-Write: X-Container-Write + - X-Container-Sync-To: X-Container-Sync-To + - X-Container-Sync-Key: X-Container-Sync-Key + - X-Versions-Location: X-Versions-Location + - X-Remove-Versions-Location: X-Remove-Versions-Location + - X-Container-Meta-name: X-Container-Meta-name + - X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin + - X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age + - X-Container-Meta-Access-Control-Expose-Headers: X-Container-Meta-Access-Control-Expose-Headers + - X-Container-Meta-Quota-Bytes: X-Container-Meta-Quota-Bytes + - X-Container-Meta-Quota-Count: X-Container-Meta-Quota-Count + - X-Container-Meta-Web-Directory-Type: X-Container-Meta-Web-Directory-Type + - Content-Type: Content-Type + - X-Detect-Content-Type: X-Detect-Content-Type + - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key + - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2 + - X-Trans-Id-Extra: X-Trans-Id-Extra + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - Date: Date + - X-Timestamp: X-Timestamp + - Content-Length: Content-Length + - Content-Type: Content-Type + - X-Trans-Id: X-Trans-Id + + + + + +Show container metadata +======================= + +.. rest_method:: HEAD /v1/{account}/{container} + +Shows container metadata, including the number of objects and the total bytes of all objects stored in the container. + +Show container metadata request: + +:: + + curl -i $publicURL/marktwain -X HEAD -H "X-Auth-Token: $token" + + + + +:: + + HTTP/1.1 204 No Content + Content-Length: 0 + X-Container-Object-Count: 1 + Accept-Ranges: bytes + X-Container-Meta-Book: TomSawyer + X-Timestamp: 1389727543.65372 + X-Container-Meta-Author: SamuelClemens + X-Container-Bytes-Used: 14 + Content-Type: text/plain; charset=utf-8 + X-Trans-Id: tx0287b982a268461b9ec14-0052d826e2 + Date: Thu, 16 Jan 2014 18:37:22 GMT + + +If the request succeeds, the operation returns the ``No Content +(204)`` response code. + +Error response codes:204, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - account: account + - container: container + - X-Auth-Token: X-Auth-Token + - X-Newest: X-Newest + - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key + - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2 + - X-Trans-Id-Extra: X-Trans-Id-Extra + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - X-Container-Sync-Key: X-Container-Sync-Key + - X-Container-Meta-name: X-Container-Meta-name + - Content-Length: Content-Length + - X-Container-Object-Count: X-Container-Object-Count + - X-Container-Write: X-Container-Write + - X-Container-Meta-Quota-Count: X-Container-Meta-Quota-Count + - Accept-Ranges: Accept-Ranges + - X-Container-Read: X-Container-Read + - X-Container-Meta-Access-Control-Expose-Headers: X-Container-Meta-Access-Control-Expose-Headers + - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key + - X-Container-Bytes-Used: X-Container-Bytes-Used + - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2 + - X-Timestamp: X-Timestamp + - X-Container-Meta-Access-Control-Allow-Origin: X-Container-Meta-Access-Control-Allow-Origin + - X-Container-Meta-Access-Control-Max-Age: X-Container-Meta-Access-Control-Max-Age + - Date: Date + - X-Trans-Id: X-Trans-Id + - X-Container-Sync-To: X-Container-Sync-To + - Content-Type: Content-Type + - X-Container-Meta-Quota-Bytes: X-Container-Meta-Quota-Bytes + - X-Versions-Location: X-Versions-Location + + + + + +Delete container +================ + +.. rest_method:: DELETE /v1/{account}/{container} + +Deletes an empty container. + +This operation fails unless the container is empty. An empty +container has no objects. + +Delete the ``steven`` container: + +:: + + curl -i $publicURL/steven -X DELETE -H "X-Auth-Token: $token" + + +If the container does not exist, the response is: + +:: + + HTTP/1.1 404 Not Found + Content-Length: 70 + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: tx4d728126b17b43b598bf7-0052d81e34 + Date: Thu, 16 Jan 2014 18:00:20 GMT + + +If the container exists and the deletion succeeds, the response is: + +:: + + HTTP/1.1 204 No Content + Content-Length: 0 + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: txf76c375ebece4df19c84c-0052d81f14 + Date: Thu, 16 Jan 2014 18:04:04 GMT + + +If the container exists but is not empty, the response is: + +:: + + HTTP/1.1 409 Conflict + Content-Length: 95 + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: tx7782dc6a97b94a46956b5-0052d81f6b + Date: Thu, 16 Jan 2014 18:05:31 GMT + +

Conflict +

+

There was a conflict when trying to complete your request. +

+ + +Error response codes:404,204,409, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - account: account + - container: container + - X-Auth-Token: X-Auth-Token + - X-Container-Meta-Temp-URL-Key: X-Container-Meta-Temp-URL-Key + - X-Container-Meta-Temp-URL-Key-2: X-Container-Meta-Temp-URL-Key-2 + - X-Trans-Id-Extra: X-Trans-Id-Extra + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - Date: Date + - X-Timestamp: X-Timestamp + - Content-Length: Content-Length + - Content-Type: Content-Type + - X-Trans-Id: X-Trans-Id + + + + + + diff --git a/api-ref/source/storage-object-services.inc b/api-ref/source/storage-object-services.inc new file mode 100644 index 0000000000..56d861158d --- /dev/null +++ b/api-ref/source/storage-object-services.inc @@ -0,0 +1,687 @@ +.. -*- rst -*- + +======= +Objects +======= + +Creates, replaces, shows details for, and deletes objects. Copies +objects from another object with a new or different name. Updates +object metadata. + + +Get object content and metadata +=============================== + +.. rest_method:: GET /v1/{account}/{container}/{object} + +Downloads the object content and gets the object metadata. + +This operation returns the object metadata in the response headers +and the object content in the response body. + +If this is a large object, the response body contains the +concatenated content of the segment objects. To get the manifest +instead of concatenated segment objects for a static large object, +use the ``multipart-manifest`` query parameter. + +Example requests and responses: + +- Show object details for the ``goodbye`` object in the + ``marktwain`` container: + + :: + + curl -i $publicURL/marktwain/goodbye -X GET -H "X-Auth-Token: $token" + + + + + :: + + HTTP/1.1 200 OK + Content-Length: 14 + Accept-Ranges: bytes + Last-Modified: Wed, 15 Jan 2014 16:41:49 GMT + Etag: 451e372e48e0f6b1114fa0724aa79fa1 + X-Timestamp: 1389804109.39027 + X-Object-Meta-Orig-Filename: goodbyeworld.txt + Content-Type: application/octet-stream + X-Trans-Id: tx8145a190241f4cf6b05f5-0052d82a34 + Date: Thu, 16 Jan 2014 18:51:32 GMT + Goodbye World! + + +- Show object details for the ``goodbye`` object, which does not + exist, in the ``janeausten`` container: + + :: + + curl -i $publicURL/janeausten/goodbye -X GET -H "X-Auth-Token: $token" + + + + + :: + + HTTP/1.1 404 Not Found + Content-Length: 70 + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: tx073f7cbb850c4c99934b9-0052d82b04 + Date: Thu, 16 Jan 2014 18:55:00 GMT + +

Not Found +

+

The resource could not be found. +

+ + + +The operation returns the ``Range Not Satisfiable (416)`` response +code for any ranged GET requests that specify more than: + +- Fifty ranges. + +- Three overlapping ranges. + +- Eight non-increasing ranges. + + +Normal response codes: 200 +Error response codes:416,404, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - account: account + - object: object + - container: container + - X-Auth-Token: X-Auth-Token + - X-Newest: X-Newest + - temp_url_sig: temp_url_sig + - temp_url_expires: temp_url_expires + - filename: filename + - multipart-manifest: multipart-manifest + - Range: Range + - If-Match: If-Match + - If-None-Match: If-None-Match + - If-Modified-Since: If-Modified-Since + - If-Unmodified-Since: If-Unmodified-Since + - X-Trans-Id-Extra: X-Trans-Id-Extra + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - Content-Length: Content-Length + - X-Object-Meta-name: X-Object-Meta-name + - Content-Disposition: Content-Disposition + - Content-Encoding: Content-Encoding + - X-Delete-At: X-Delete-At + - Accept-Ranges: Accept-Ranges + - X-Object-Manifest: X-Object-Manifest + - Last-Modified: Last-Modified + - ETag: ETag + - X-Timestamp: X-Timestamp + - X-Trans-Id: X-Trans-Id + - Date: Date + - X-Static-Large-Object: X-Static-Large-Object + - Content-Type: Content-Type + + + +Response Example +---------------- + +See examples above. + + +Create or replace object +======================== + +.. rest_method:: PUT /v1/{account}/{container}/{object} + +Creates an object with data content and metadata, or replaces an existing object with data content and metadata. + +The PUT operation always creates an object. If you use this +operation on an existing object, you replace the existing object +and metadata rather than modifying the object. Consequently, this +operation returns the ``Created (201)`` response code. + +If you use this operation to copy a manifest object, the new object +is a normal object and not a copy of the manifest. Instead it is a +concatenation of all the segment objects. This means that you +cannot copy objects larger than 5 GB. + +Example requests and responses: + +- Create object: + + :: + + curl -i $publicURL/janeausten/helloworld.txt -X PUT -H "Content-Length: 1" -H "Content-Type: text/html; charset=UTF-8" -H "X-Auth-Token: $token" + + + + + :: + + HTTP/1.1 201 Created + Last-Modified: Fri, 17 Jan 2014 17:28:35 GMT + Content-Length: 116 + Etag: d41d8cd98f00b204e9800998ecf8427e + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843 + Date: Fri, 17 Jan 2014 17:28:35 GMT + + +- Replace object: + + :: + + curl -i $publicURL/janeausten/helloworld -X PUT -H "Content-Length: 0" -H "X-Auth-Token: $token" + + + + + :: + + HTTP/1.1 201 Created + Last-Modified: Fri, 17 Jan 2014 17:28:35 GMT + Content-Length: 116 + Etag: d41d8cd98f00b204e9800998ecf8427e + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: tx4d5e4f06d357462bb732f-0052d96843 + Date: Fri, 17 Jan 2014 17:28:35 GMT + + +The ``Created (201)`` response code indicates a successful write. + +If the request times out, the operation returns the ``Request +Timeout (408)`` response code. + +The ``Length Required (411)`` response code indicates a missing +``Transfer-Encoding`` or ``Content-Length`` request header. + +If the MD5 checksum of the data that is written to the object store +does not match the optional ``ETag`` value, the operation returns +the ``Unprocessable Entity (422)`` response code. + +Error response codes:201,422,411,408, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - account: account + - object: object + - container: container + - multipart-manifest: multipart-manifest + - temp_url_sig: temp_url_sig + - temp_url_expires: temp_url_expires + - filename: filename + - X-Object-Manifest: X-Object-Manifest + - X-Auth-Token: X-Auth-Token + - Content-Length: Content-Length + - Transfer-Encoding: Transfer-Encoding + - Content-Type: Content-Type + - X-Detect-Content-Type: X-Detect-Content-Type + - X-Copy-From: X-Copy-From + - ETag: ETag + - Content-Disposition: Content-Disposition + - Content-Encoding: Content-Encoding + - X-Delete-At: X-Delete-At + - X-Delete-After: X-Delete-After + - X-Object-Meta-name: X-Object-Meta-name + - If-None-Match: If-None-Match + - X-Trans-Id-Extra: X-Trans-Id-Extra + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - Content-Length: Content-Length + - ETag: ETag + - X-Timestamp: X-Timestamp + - X-Trans-Id: X-Trans-Id + - Date: Date + - Content-Type: Content-Type + - last_modified: last_modified + + + + + + + + +Copy object +=========== + +.. rest_method:: COPY /v1/{account}/{container}/{object} + +Copies an object to another object in the object store. + +You can copy an object to a new object with the same name. Copying +to the same name is an alternative to using POST to add metadata to +an object. With POST , you must specify all the metadata. With COPY +, you can add additional metadata to the object. + +With COPY , you can set the ``X-Fresh-Metadata`` header to ``true`` +to copy the object without any existing metadata. + +Alternatively, you can use PUT with the ``X-Copy-From`` request +header to accomplish the same operation as the COPY object +operation. + +The PUT operation always creates an object. If you use this +operation on an existing object, you replace the existing object +and metadata rather than modifying the object. Consequently, this +operation returns the ``Created (201)`` response code. + +If you use this operation to copy a manifest object, the new object +is a normal object and not a copy of the manifest. Instead it is a +concatenation of all the segment objects. This means that you +cannot copy objects larger than 5 GB in size. All metadata is +preserved during the object copy. If you specify metadata on the +request to copy the object, either PUT or COPY , the metadata +overwrites any conflicting keys on the target (new) object. + +Example requests and responses: + +- Copy the ``goodbye`` object from the ``marktwain`` container to + the ``janeausten`` container: + + :: + + curl -i $publicURL/marktwain/goodbye -X COPY -H "X-Auth-Token: $token" -H "Destination: janeausten/goodbye" + + + + + :: + + HTTP/1.1 201 Created + Content-Length: 0 + X-Copied-From-Last-Modified: Thu, 16 Jan 2014 21:19:45 GMT + X-Copied-From: marktwain/goodbye + Last-Modified: Fri, 17 Jan 2014 18:22:57 GMT + Etag: 451e372e48e0f6b1114fa0724aa79fa1 + Content-Type: text/html; charset=UTF-8 + X-Object-Meta-Movie: AmericanPie + X-Trans-Id: txdcb481ad49d24e9a81107-0052d97501 + Date: Fri, 17 Jan 2014 18:22:57 GMT + + +- Alternatively, you can use PUT to copy the ``goodbye`` object from + the ``marktwain`` container to the ``janeausten`` container. This + request requires a ``Content-Length`` header, even if it is set + to zero (0). + + :: + + curl -i $publicURL/janeausten/goodbye -X PUT -H "X-Auth-Token: $token" -H "X-Copy-From: /marktwain/goodbye" -H "Content-Length: 0" + + + + + :: + + HTTP/1.1 201 Created + Content-Length: 0 + X-Copied-From-Last-Modified: Thu, 16 Jan 2014 21:19:45 GMT + X-Copied-From: marktwain/goodbye + Last-Modified: Fri, 17 Jan 2014 18:22:57 GMT + Etag: 451e372e48e0f6b1114fa0724aa79fa1 + Content-Type: text/html; charset=UTF-8 + X-Object-Meta-Movie: AmericanPie + X-Trans-Id: txdcb481ad49d24e9a81107-0052d97501 + Date: Fri, 17 Jan 2014 18:22:57 GMT + + +When several replicas exist, the system copies from the most recent +replica. That is, the COPY operation behaves as though the +``X-Newest`` header is in the request. + +Error response codes:201, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - account: account + - object: object + - container: container + - X-Auth-Token: X-Auth-Token + - Destination: Destination + - Content-Type: Content-Type + - Content-Encoding: Content-Encoding + - Content-Disposition: Content-Disposition + - X-Object-Meta-name: X-Object-Meta-name + - X-Fresh-Metadata: X-Fresh-Metadata + - X-Trans-Id-Extra: X-Trans-Id-Extra + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - Content-Length: Content-Length + - X-Object-Meta-name: X-Object-Meta-name + - X-Copied-From-Last-Modified: X-Copied-From-Last-Modified + - X-Copied-From: X-Copied-From + - Last-Modified: Last-Modified + - ETag: ETag + - X-Timestamp: X-Timestamp + - X-Trans-Id: X-Trans-Id + - Date: Date + - Content-Type: Content-Type + + + + + +Delete object +============= + +.. rest_method:: DELETE /v1/{account}/{container}/{object} + +Permanently deletes an object from the object store. + +You can use the COPY method to copy the object to a new location. +Then, use the DELETE method to delete the original object. + +Object deletion occurs immediately at request time. Any subsequent +GET , HEAD , POST , or DELETE operations return a ``404 Not Found`` +error code. + +For static large object manifests, you can add the ``?multipart- +manifest=delete`` query parameter. This operation deletes the +segment objects and if all deletions succeed, this operation +deletes the manifest object. + +Example request and response: + +- Delete the ``helloworld`` object from the ``marktwain`` container: + + :: + + curl -i $publicURL/marktwain/helloworld -X DELETE -H "X-Auth-Token: $token" + + + + + :: + + HTTP/1.1 204 No Content + Content-Length: 0 + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: tx36c7606fcd1843f59167c-0052d6fdac + Date: Wed, 15 Jan 2014 21:29:16 GMT + + +Typically, the DELETE operation does not return a response body. +However, with the ``multipart-manifest=delete`` query parameter, +the response body contains a list of manifest and segment objects +and the status of their DELETE operations. + +Error response codes:204, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - account: account + - object: object + - container: container + - multipart-manifest: multipart-manifest + - X-Auth-Token: X-Auth-Token + - X-Trans-Id-Extra: X-Trans-Id-Extra + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - Date: Date + - X-Timestamp: X-Timestamp + - Content-Length: Content-Length + - Content-Type: Content-Type + - X-Trans-Id: X-Trans-Id + + + + + +Show object metadata +==================== + +.. rest_method:: HEAD /v1/{account}/{container}/{object} + +Shows object metadata. + +If the ``Content-Length`` response header is non-zero, the example +cURL command stalls after it prints the response headers because it +is waiting for a response body. However, the Object Storage system +does not return a response body for the HEAD operation. + +Example requests and responses: + +- Show object metadata: + + :: + + curl -i $publicURL/marktwain/goodbye -X HEAD -H "X-Auth-Token: $token" + + + + + :: + + HTTP/1.1 200 OK + Content-Length: 14 + Accept-Ranges: bytes + Last-Modified: Thu, 16 Jan 2014 21:12:31 GMT + Etag: 451e372e48e0f6b1114fa0724aa79fa1 + X-Timestamp: 1389906751.73463 + X-Object-Meta-Book: GoodbyeColumbus + Content-Type: application/octet-stream + X-Trans-Id: tx37ea34dcd1ed48ca9bc7d-0052d84b6f + Date: Thu, 16 Jan 2014 21:13:19 GMT + + +If the request succeeds, the operation returns the ``200`` response +code. + + +Normal response codes: 200 +Error response codes:204, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - account: account + - object: object + - container: container + - X-Auth-Token: X-Auth-Token + - temp_url_sig: temp_url_sig + - temp_url_expires: temp_url_expires + - filename: filename + - X-Newest: X-Newest + - X-Trans-Id-Extra: X-Trans-Id-Extra + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - Last-Modified: Last-Modified + - Content-Length: Content-Length + - X-Object-Meta-name: X-Object-Meta-name + - Content-Disposition: Content-Disposition + - Content-Encoding: Content-Encoding + - X-Delete-At: X-Delete-At + - X-Object-Manifest: X-Object-Manifest + - Last-Modified: Last-Modified + - ETag: ETag + - X-Timestamp: X-Timestamp + - X-Trans-Id: X-Trans-Id + - Date: Date + - X-Static-Large-Object: X-Static-Large-Object + - Content-Type: Content-Type + + + +Response Example +---------------- + +See examples above. + + + +Create or update object metadata +================================ + +.. rest_method:: POST /v1/{account}/{container}/{object} + +Creates or updates object metadata. + +To create or update custom metadata, use the ``X-Object- +Meta-{name}`` header, where ``{name}`` is the name of the metadata +item. + +In addition to the custom metadata, you can update the ``Content- +Type``, ``Content-Encoding``, ``Content-Disposition``, and ``X +-Delete-At`` system metadata items. However you cannot update other +system metadata, such as ``Content-Length`` or ``Last-Modified``. + +You can use COPY as an alternate to the POST operation by copying +to the same object. With the POST operation you must specify all +metadata items, whereas with the COPY operation, you need to +specify only changed or additional items. + +All metadata is preserved during the object copy. If you specify +metadata on the request to copy the object, either PUT or COPY , +the metadata overwrites any conflicting keys on the target (new) +object. + +A POST request deletes any existing custom metadata that you added +with a previous PUT or POST request. Consequently, you must specify +all custom metadata in the request. However, system metadata is +unchanged by the POST request unless you explicitly supply it in a +request header. + +You can also set the ``X-Delete-At`` or ``X-Delete-After`` header +to define when to expire the object. + +When used as described in this section, the POST operation creates +or replaces metadata. This form of the operation has no request +body. + +You can also use the `form POST feature +`_ to upload objects. + +Example requests and responses: + +- Create object metadata: + + :: + + curl -i $publicURL/marktwain/goodbye -X POST -H "X-Auth-Token: $token" -H "X-Object-Meta-Book: GoodbyeColumbus" + + + + + :: + + HTTP/1.1 202 Accepted + Content-Length: 76 + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: txb5fb5c91ba1f4f37bb648-0052d84b3f + Date: Thu, 16 Jan 2014 21:12:31 GMT + +

Accepted +

+

The request is accepted for processing. +

+ + + +- Update object metadata: + + :: + + curl -i $publicURL/marktwain/goodbye -X POST -H "X-Auth-Token: $token" H "X-Object-Meta-Book: GoodbyeOldFriend" + + + + + :: + + HTTP/1.1 202 Accepted + Content-Length: 76 + Content-Type: text/html; charset=UTF-8 + X-Trans-Id: tx5ec7ab81cdb34ced887c8-0052d84ca4 + Date: Thu, 16 Jan 2014 21:18:28 GMT + +

Accepted +

+

The request is accepted for processing. +

+ + +Error response codes:202, + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - account: account + - object: object + - container: container + - X-Auth-Token: X-Auth-Token + - X-Object-Meta-name: X-Object-Meta-name + - X-Delete-At: X-Delete-At + - Content-Disposition: Content-Disposition + - Content-Encoding: Content-Encoding + - X-Delete-After: X-Delete-After + - Content-Type: Content-Type + - X-Detect-Content-Type: X-Detect-Content-Type + - X-Trans-Id-Extra: X-Trans-Id-Extra + + +Response Parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - Date: Date + - X-Timestamp: X-Timestamp + - Content-Length: Content-Length + - Content-Type: Content-Type + - X-Trans-Id: X-Trans-Id + + + + diff --git a/api-ref/source/storage_endpoints.inc b/api-ref/source/storage_endpoints.inc new file mode 100644 index 0000000000..41845425d4 --- /dev/null +++ b/api-ref/source/storage_endpoints.inc @@ -0,0 +1,37 @@ +.. -*- rst -*- + +========= +Endpoints +========= + +If configured, lists endpoints for an account. + + +List endpoints +============== + +.. rest_method:: GET /v1/endpoints + +Lists endpoints for an object, account, or container. + +When the cloud provider enables middleware to list the +``/endpoints/`` path, software that needs data location information +can use this call to avoid network overhead. The cloud provider can +map the ``/endpoints/`` path to another resource, so this exact +resource might vary from provider to provider. Because it goes +straight to the middleware, the call is not authenticated, so be +sure you have tightly secured the environment and network when +using this call. + +Error response codes:201, + + +Request +------- + +This operation does not accept a request body. + + + + + diff --git a/api-ref/source/storage_info.inc b/api-ref/source/storage_info.inc new file mode 100644 index 0000000000..60b4082f7c --- /dev/null +++ b/api-ref/source/storage_info.inc @@ -0,0 +1,41 @@ +.. -*- rst -*- + +=============== +Discoverability +=============== + +If configured, lists the activated capabilities for this version of +the OpenStack Object Storage API. + + +List activated capabilities +=========================== + +.. rest_method:: GET /info + +Lists the activated capabilities for this version of the OpenStack Object Storage API. + + +Normal response codes: 200 +Error response codes: + + +Request +------- + +.. rest_parameters:: parameters.yaml + + - swiftinfo_sig: swiftinfo_sig + - swiftinfo_expires: swiftinfo_expires + + + + +Response Example +---------------- + +.. literalinclude:: samples/capabilities-list-response.json + :language: javascript + + + diff --git a/test-requirements.txt b/test-requirements.txt index 3525d03615..6f237978d3 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -10,6 +10,7 @@ nosexcover nosehtmloutput oslosphinx sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3 # BSD +os-api-ref>=0.1.0 # Apache-2.0 os-testr>=0.4.1 mock>=1.0 python-swiftclient diff --git a/tox.ini b/tox.ini index 1e79f67b88..5becdf2a9e 100644 --- a/tox.ini +++ b/tox.ini @@ -59,6 +59,22 @@ commands = {posargs} [testenv:docs] commands = python setup.py build_sphinx +[testenv:api-ref] +# This environment is called from CI scripts to test and publish +# the API Ref to developer.openstack.org. +# NOTE(sdague): this target does not use constraints because +# upstream infra does not yet support it. Once that's fixed, we can +# drop the install_command. +# +# we do not use -W here because we are doing some slightly tricky +# things to build a single page document, and as such, we are ok +# ignoring the duplicate stanzas warning. +install_command = pip install -U --force-reinstall {opts} {packages} +commands = + rm -rf api-ref/build + sphinx-build -W -b html -d api-ref/build/doctrees api-ref/source api-ref/build/html + + [testenv:bandit] deps = -r{toxinidir}/test-requirements.txt commands = bandit -c bandit.yaml -r swift bin -n 5 -p gate