Skip to main content
Hitachi Vantara Knowledge

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.

NameTypeDescription
X-Auth-TokenString

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.

NameTypeDescription
Content-lengthString (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-Length is 0 (zero).

Content-TypeString (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 application/octet-stream.

Because HCP returns error information in a response body, the response to any request can include a Content-Type header.

DateDatetime (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 chunked.

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 Transfer-Encoding header.

X-Trans-IdUuid (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.

HeaderValueDescription
Cache-Controlno-cache,no-store,must- revalidateSpecifies directives that must be obeyed by all caching mechanisms along the request/response chain
Content-Security- Policydefault-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
ExpiresThu, 01 Jan 1970 00:00:00 GMTCauses the response to become stale immediately after it is sent
Pragmano-cachePrevents 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- OptionsnosniffPrevents the browser from examining the returned content to determine the content MIME type
X-DNS-Prefetch- ControloffPrevents the browser from performing domain name resolution on URLs embedded in returned content before the URLs are requested
X-Download- OptionsnoopenPrevents the browser from opening resources that are downloaded through links in the returned content
X-Frame-OptionsSAMEORIGINPrevents the browser from rendering the returned content in a frame on a page containing content not returned by the HCP system
X-XSS-Protection1; mode=blockStops 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.

Note
  • 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, and Content-Language. For more information about HTTP response headers, see the HTTP/1.1 standards (RFCs 7230 through 7237).
  • The Cache-Control and Expires headers 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 codeHTTP status codeDescription
304Not modified

One of:

  • The request included an If-None-Match header, and the ETag for the specified object matched a value specified by the header.
  • The request included an If-Modified-Since header, and the specified object was not modified after the date and time specified by the header.
401UnauthorizedToken Expired. Token Invalid. No Token Provided.
403ForbiddenAuthenticated user does not have permission to perform requested operation.
404Not FoundThe resource identified in the URL could not be found on the server.
405Method Not AllowedThe HTTP method is not supported
412Precondition Failed

One of:

  • The request included an If-Match header, and the ETag for the specified object doesn't not match any of the values specified by the header.
  • The request included an If-Unmodified-Since header, and the specified object was modified after the date and time specified by the header.
500Not Implemented

An internal error occurred.

If this error persists, contact your tenant administrator.

503Service 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.

 

  • Was this article helpful?