Requests and responses
With the HSwift API, you submit requests for operations to HCP, and HCP returns responses that indicate the outcome of the request and includes any requested information or content.
This section goes over the common request and response headers that HSwift supports. Due to storage differences, not all requests and responses from the HSwift API can be implemented when storing to HCP. This chapter highlights the ones that HCP does accept.
Requests
HSwift is an HTTP-based API. As is standard for HTTP, the structure for an HSwift request consists of a request line, request headers that qualify the request, and, if applicable, a request body.
Request line
The request line for an HSwift request specifies the operation to be performed, whether the target of the operation is an account, container, or object, and the version of HTTP on which the HSwift API is based.
In an HSwift request that uses Keystone authentication, the account name is interchangeable with the Keystone tenant authentication token.
For example, here are the Keystone tenant authentication token and account name request lines for a request to create a container named finance:
PUT /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance HTTP/1.1 PUT /swift/v1/europe/finance HTTP/1.1
If the target of the request is a container, the request line includes a forward slash followed by the container name.
If the target of the operation is an object, the request line includes a forward slash followed by the object name following the container name.
For example, here are the Keystone tenant authentication token and account name request lines for a request to create an object named Q4_2012:
PUT /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/Q4_2012.ppt HTTP/1.1 PUT /swift/v1/europe/finance/Q4_2012.ppt HTTP/1.1
If the request uses headers such as the X-Container-Write header it is shown under the request.
For example, here are the Keystone tenant authentication token and account name request lines and X-Write-Container headers for a request to create a container named finance and add an ACL to the container:
PUT /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e/finance/Q4_2012.ppt/ HTTP/1.1 "X-Container-Write: *" PUT /swift/v1/europe/finance/Q4_2012.ppt/ HTTP/1.1 "X-Container-Write: *"
If the request uses any query parameters, those parameters are appended to the last one of the items listed above.
For example, here are the Keystone tenant authentication token and account name request lines for a request to list all containers in between the letters E and S:
GET /swift/v1/AUTH_6b6884ebb6f441cfbb7e740f6a927c9e?marker=e&end_marker=s/ HTTP/1.1 GET /swift/v1/europe?marker=e&end_marker=s/ HTTP/1.1
If the request includes invalid query parameters, those parameters are ignored.
Common request headers
Some request headers are common to all HSwift requests. The table below describes those headers.
Request header names are not case sensitive. Depending on the header, the header values may or may not be case sensitive.
| Name | Type | Description |
| X-Auth-Token | String |
Used to supply the Keystone authentication token or local authentication token. Replace the Keystone authentication token with the prefix HCP, followed by your Local Authentication token, in the format: "X-Auth-Token: HCP base64-encoded-username:md5-encoded-password" For example: "X-Auth-Token: HCP bGdyZWVu:a3b9c163f6c520407ff34cfdb83ca5c6" |
Responses
The response to an request consists of a response status line, response headers that provide information about the execution and outcome of the request, and, if applicable, a response body. The response to an unsuccessful request (except for HEAD requests) includes an error response body.
Response status line
The status line returned in response to an HSwift request specifies the version of HTTP on which the HSwift API is based and an HTTP status code that indicates the outcome of the request. HTTP status codes in the 2xx range indicate that the requested operation was successful. HTTP status codes in the 3xx, 4xx, and 5xx ranges, typically indicate that an error occurred and HCP did not perform the requested operation.
Here's an example of a response status line that indicates that the requested operation was successful:
HTTP/1.1 200 Success
Here's an example of a response status line for an unsuccessful operation:
HTTP/1.1 409 Conflict
Common response headers
Some response headers are common to all HSwift requests, while some are specific to certain requests. The table below describes some of the common response headers.
| Name | Type | Description |
| Content-length | String (Required) |
The size, in bytes, of the response body if HCP can determine the size before formulating the response. If the response does not include a response body, the value of the |
| Content-Type | String (Required if the Content-Length is greater than 0) |
The Internet media type of the response body if HCP can determine the Internet media type. If HCP cannot determine the Internet media type, the value of this header is Because HCP returns error information in a response body, the response to any request can include a |
| Date | Datetime (Required) |
The date and time at which HCP responded to the request in Greenwich Mean Time (GMT). The date and time are returned in this format: DDD dd MMM yyyy HH:mm:ss GMT For example: Thu, 14 Mat 2013 14:27:05 GMT |
| Transfer-Encoding |
Always This header is returned if the response includes a response body but HCP cannot determine the size of the response body before formulating the response. Because HCP returns error information in a response body, the response to any request can include a | |
| X-Trans-Id | Uuid (Required) | HCP returns a universally unique identifier (UUID). This UUID does not map to any entries in the HCP database. |
Some common response headers address browser security concerns. These headers have fixed values. The table below describes these headers.
| Header | Value | Description |
| Cache-Control | no-cache,no-store,must- revalidate | Specifies directives that must be obeyed by all caching mechanisms along the request/response chain |
| Content-Security- Policy | default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe- inline'; connect-src 'self'; img-src 'self'; style-src 'self' 'unsafe-inline'; object-src 'self'; frame-ancestors 'self'; | Restricts the content that the browser can load to the sources specified by the header value |
| Expires | Thu, 01 Jan 1970 00:00:00 GMT | Causes the response to become stale immediately after it is sent |
| Pragma | no-cache | Prevents the response from being used for subsequent requests for the same resource without the browser first checking whether the resource has changed |
| X-Content-Type- Options | nosniff | Prevents the browser from examining the returned content to determine the content MIME type |
| X-DNS-Prefetch- Control | off | Prevents the browser from performing domain name resolution on URLs embedded in returned content before the URLs are requested |
| X-Download- Options | noopen | Prevents the browser from opening resources that are downloaded through links in the returned content |
| X-Frame-Options | SAMEORIGIN | Prevents the browser from rendering the returned content in a frame on a page containing content not returned by the HCP system |
| X-XSS-Protection | 1; mode=block | Stops the browser from loading the returned content if the browser detects reflected cross-site scripting (XSS) in the response |
For information about request-specific response headers, see the "Response header" section for each type of operation you can perform with the HSwift API.
- HCP can also return several standard HTTP response headers that are not described in this book. Among others, these include
Connection,Content-Disposition,Content-Encoding, andContent-Language. For more information about HTTP response headers, see the HTTP/1.1 standards (RFCs 7230 through 7237). - The
Cache-ControlandExpiresheaders are not returned with error responses.
Error response body
When an HSwift request results in an error, HCP returns information about the error in an error request body. An error request body contains HTML in this format:
<html>
<h1>HTTP-status-code</h1>
<p>error-message</p>
</html>
Error codes
Every error response body contains an HTTP status code and a description that provides more information about the error. The error codes themselves can be found with the response header. A single HTTP status code can correspond to multiple error codes.
The table below describes the error codes that can be returned in response to HSwift requests.
| Error code | HTTP status code | Description |
| 304 | Not modified |
One of:
|
| 401 | Unauthorized | Token Expired. Token Invalid. No Token Provided. |
| 403 | Forbidden | Authenticated user does not have permission to perform requested operation. |
| 404 | Not Found | The resource identified in the URL could not be found on the server. |
| 405 | Method Not Allowed | The HTTP method is not supported |
| 412 | Precondition Failed |
One of:
|
| 500 | Not Implemented |
An internal error occurred. If this error persists, contact your tenant administrator. |
| 503 | Service Unavailable |
HCP is temporarily unable to handle the request, probably due to system overload, maintenance, or upgrade. Try the request again, gradually increasing the delay between each successive attempt. If this error persists, contact your tenant administrator. |